@herbertgao/pi-extensions 2026.8.15 → 2026.9.1

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

@@ -12,6 +12,7 @@ import * as nodeFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL, URL } from "node:url";
+import { BoundedFifoMap } from "../bounded-cache.js";
 import { getProjectIgnoreMatcher, isExcludedDirName } from "../file-utils.js";
 import { recordLsp } from "../widget-state.js";
 import { applyAuxiliarySuppressions } from "../dispatch/auxiliary-lsp.js";
@@ -22,7 +23,10 @@ import { logSessionStart } from "../sessionstart-logger.js";
 import { incrementDegradationCount, recordDegradation, recordDegradationOnce, } from "../degradation-ledger.js";
 import { isLspSpawnAllowedByTrust, assertInstallAllowed, projectTrustDenialReason, } from "../project-trust.js";
 import { shouldPreferPullOnlyDiagnostics } from "../lsp-budget.js";
-import { withDeadline, withTimeout } from "../deadline-utils.js";
+import { sampleProcessTreeCpuPercent } from "../resource-sampler.js";
+import { bounded, withDeadline, withTimeout } from "../deadline-utils.js";
+import { getAmbientAbortSignal } from "../safe-spawn.js";
+import { abortDeferredLspWork } from "../deferred-lsp-work.js";
 import { acquireWorkspaceSweepHold, clearWorkspaceSweepHoldForSessionStart, } from "./workspace-sweep-hold.js";
 import { DocumentDriftTracker, fingerprintDocumentContent, } from "./document-drift.js";
 import { markPendingAuxiliaryCoverage, napiFallbackCoveredSince, } from "./pending-aux-coverage.js";
@@ -37,7 +41,7 @@ import { getServersForFileWithConfig, getServerInitOverride, } from "./config.js
 import { getSessionRootsForTelemetry, isOutsideAllSessionRoots, } from "./session-roots.js";
 import { getProcessSingleton } from "../process-singletons.js";
 import { getLanguageId } from "./language.js";
-import { LSP_SERVERS, enforceLspRootCeiling, hasProjectBoundaryMarker, isDirectLspCommandTemporarilyUnavailable, resetClassicTsRepairGuard, } from "./server.js";
+import { LSP_SERVERS, enforceLspRootCeiling, hasProjectBoundaryMarker, isDirectLspCommandTemporarilyUnavailable, resetClassicTsRepairGuard, resetLspLaunchAvailabilityGeneration, } from "./server.js";
 import { classifyCascadeWaitTier, classifyServerWaitTier, getStrategy, } from "./wait-policy/index.js";
 const WORKSPACE_ATTRIBUTION_CLIENT_CAP = 16;
 import { raceToCompletion } from "./aggregation.js";
@@ -468,6 +472,19 @@ function notifyWriteBudgetMs() {
     const raw = Number(process.env.PI_LENS_LSP_NOTIFY_BUDGET_MS);
     return Number.isFinite(raw) && raw > 0 ? raw : 2000;
 }
+// #2239: the SAME effective per-server wait floor `getClientForFile` uses to
+// size its own acquisition race — the caller's declared budget, raised to
+// whatever the file's primary server(s) configure via `clientWaitTimeoutMs`
+// (Ruby 30s, and the Bash/JSON/Vue/Svelte/Prisma overrides #2233 added). A
+// cold primary spawn is allowed to run this long, so anything downstream that
+// charges itself against `maxWaitMs` alone — rather than this floor — sees an
+// already-elapsed time it never budgeted for and clamps to zero.
+function primaryServerWaitFloorMs(filePath, maxWaitMs) {
+    const serverWaitOverrideMs = getServersForFileWithConfig(filePath)
+        .filter((s) => s.role !== "auxiliary")
+        .reduce((max, server) => Math.max(max, server.clientWaitTimeoutMs ?? 0), 0);
+    return Math.max(maxWaitMs ?? 0, serverWaitOverrideMs);
+}
 // #1459: how long ONE auxiliary notify write may stay outstanding before the
 // server counts as wedged rather than merely slow. A scanner whose per-file work
 // exceeds the write budget is normal (opengrep routinely needs >2s on a large
@@ -479,6 +496,30 @@ const NOTIFY_WEDGED_BUDGET_MULTIPLIER = 5;
 function notifyWedgedMs() {
     return notifyWriteBudgetMs() * NOTIFY_WEDGED_BUDGET_MULTIPLIER;
 }
+// #2358: the wedge window's teardown decision gained a liveness discriminator.
+// The fixed window above stays the FLOOR; a server whose drain history says it
+// answers per-write in `ewmaMs` with `unacked` documents queued earns
+// `k x ewmaMs x unacked` of patience instead — the issue's "a server that
+// historically answers in 855 ms with 8 writes queued earns 15-20 s". The cap
+// bounds the whole thing so a busy-but-never-draining server still respawns.
+const NOTIFY_WEDGED_EWMA_MULTIPLIER = 2;
+const NOTIFY_WEDGED_CAP_MS = 60_000;
+function notifyWedgedCapMs() {
+    const raw = Number(process.env.PI_LENS_LSP_NOTIFY_WEDGED_CAP_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : NOTIFY_WEDGED_CAP_MS;
+}
+// #2358: how long the CPU-liveness discriminator watches the server between
+// two process-CPU samples before deciding "busy" vs "flat". Only ever spent
+// on a server whose write is already past its patience window — never on the
+// per-edit hot path.
+function notifyStallCpuSampleMs() {
+    const raw = Number(process.env.PI_LENS_LSP_NOTIFY_STALL_CPU_SAMPLE_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 1200;
+}
+// A server burning more than this percent of one core across the sample
+// window counts as BUSY (progressing), not flat (wedged). A single-threaded
+// scanner under burst sits near 100; an idle or dead one near 0.
+const NOTIFY_STALL_CPU_BUSY_FLOOR_PERCENT = 10;
 // #1714: how many document notifies one auxiliary may hold UNACKNOWLEDGED
 // before the next notify has to prove the server drained its input.
 //
@@ -712,6 +753,22 @@ export class LSPService {
      * successful write clears its entry.
      */
     notifyWriteBackpressureStreak = new Map();
+    /**
+     * #2358: EWMA of one auxiliary's per-document drain latency
+     * (ms per unacknowledged write), keyed by "serverId:normalizedRoot".
+     *
+     * Updated from DRAINED notify barriers only: the round-trip proves the
+     * server processed its `outstanding` backlog, and
+     * duration / outstanding is the per-write service time a single-threaded
+     * scanner actually achieves under load. The breaker grants a wedged write
+     * `k x ewma x unacked` of patience from it, so a slow-but-alive scanner is
+     * not killed at the fixed window by construction (#2358).
+     *
+     * Cleared by the service teardown (via `session_start`) like the rest of
+     * the breaker state; a stale throughput estimate from a previous session's
+     * client must not price the next one.
+     */
+    auxNotifyDrainLatencyEwma = new Map();
     /**
      * #1714: unacknowledged auxiliary document notifies per server key
      * ("serverId:normalizedRoot" — the same identity as every other gate here).
@@ -748,6 +805,15 @@ export class LSPService {
      * never lands is still demoted (see {@link demoteForNotifyStall}).
      */
     outstandingAuxNotifyWrites = new Map();
+    /**
+     * #2356: auxiliary clients removed by the notify-stall breaker are a
+     * temporary absence, not a missing scanner. Keep the demotion identity after
+     * deleting the client so the turn-end late-coverage probe can re-arm the
+     * pending pair until a replacement is published (or its existing bounded
+     * re-arm ceiling is reached). A successful replacement removes the marker.
+     */
+    static MAX_NOTIFY_STALL_DEMOTIONS = 50;
+    notifyStallDemotions = new BoundedFifoMap(LSPService.MAX_NOTIFY_STALL_DEMOTIONS);
     /** LRU clock for capacity eviction, keyed by the canonical server/root key. */
     clientLastUsedAt = new Map();
     /**
@@ -948,6 +1014,7 @@ export class LSPService {
             return false;
         }
         const [victimKey, victimClient] = victim;
+        this.releaseOutstandingAuxNotifyWrite(victimKey);
         await victimClient.shutdown({ reason: "client_ceiling_lru" });
         this.state.clients.delete(victimKey);
         this.state.clientSpawnedAt.delete(victimKey);
@@ -964,6 +1031,15 @@ export class LSPService {
             clearTimeout(timer);
         this.typeScriptIdleTimers.delete(key);
     }
+    /** Release a notify token and its timer when its client generation retires. */
+    releaseOutstandingAuxNotifyWrite(key, token) {
+        const current = this.outstandingAuxNotifyWrites.get(key);
+        if (!current || (token !== undefined && current !== token))
+            return;
+        clearTimeout(current.wedgeTimer);
+        this.outstandingAuxNotifyWrites.delete(key);
+        current.resolveSettled();
+    }
     scheduleTypeScriptIdleEviction(key) {
         if (!key.startsWith("typescript:"))
             return;
@@ -989,6 +1065,7 @@ export class LSPService {
                 // Publish the cold state synchronously before awaiting teardown. A request
                 // arriving while shutdown is in progress therefore waits on the spawn gate
                 // and creates a fresh client; it can never receive this retiring one.
+                this.releaseOutstandingAuxNotifyWrite(key);
                 this.state.clients.delete(key);
                 this.state.clientSpawnedAt.delete(key);
                 this.state.demonstratedReady.delete(key);
@@ -1130,23 +1207,130 @@ export class LSPService {
             return;
         }
         this.notifyWriteBackpressureStreak.delete(key);
-        this.demoteForNotifyStall(key, entry, filePath, {
+        // #2358: the consecutive-timeout ladder lands here too, and its verdict
+        // must not kill a server that is demonstrably BUSY. The guarded demotion
+        // samples the live process CPU and merely resets the ladder (the next
+        // three timeouts re-try) when the server is progressing — the wedged-write
+        // path's cap owns a busy-but-never-draining server, not this streak.
+        void this.demoteNotifyStallCpuGuarded(key, entry, filePath, {
             consecutiveTimeouts: NOTIFY_BACKPRESSURE_BROKEN_AFTER,
         });
     }
+    /**
+     * #2358: liveness-guarded teardown for the STREAK ladder.
+     *
+     * The wedged-write path ({@link decideNotifyStallTeardown}) keeps its own
+     * re-arm loop so a busy server's outstanding write stays un-torn-down; the
+     * streak ladder has no write to hold — it simply does not demote, and the
+     * next three timeouts re-attempt. Generation-guarded after the await so a
+     * client replaced mid-sample is never demoted for a verdict about its
+     * predecessor.
+     */
+    async demoteNotifyStallCpuGuarded(key, entry, filePath, reason) {
+        if (this.state.clients.get(key) !== entry.client)
+            return;
+        // The CPU verdict is asynchronous, but the streak has already committed to
+        // this client's teardown path. Release the TypeScript idle-timer ownership
+        // before sampling so another idle callback cannot target the same client
+        // while the verdict is in flight. A BUSY verdict below re-arms a fresh timer.
+        this.clearTypeScriptIdleTimer(key);
+        const verdict = await this.notifyStallCpuVerdict(entry);
+        if (verdict.cpuVerdict === "busy") {
+            if (this.state.clients.get(key) === entry.client) {
+                this.scheduleTypeScriptIdleEviction(key);
+            }
+            this.logNotifyStallCpuBusy(key, entry, filePath, 0, verdict);
+            return;
+        }
+        if (this.state.clients.get(key) !== entry.client)
+            return;
+        this.demoteForNotifyStall(key, entry, filePath, {
+            ...reason,
+            discriminator: "consecutive-timeouts",
+            cpuVerdict: verdict.cpuVerdict,
+        });
+    }
+    /**
+     * #2358: classify a stalled server's live process CPU.
+     *
+     * A client with no process handle (a test/mock double, a legacy client)
+     * reports "unmeasured" — the caller keeps the pre-#2358 demote-at-budget
+     * behavior, because there is no liveness evidence to override it. A sampled
+     * process that burns a core is BUSY; anything else is FLAT, including a
+     * query that failed to resolve the pid — a server we cannot measure is not
+     * proven busy, and the replacement self-heal is cheap.
+     */
+    async notifyStallCpuVerdict(entry) {
+        const pid = entry.client.getProcessPid?.();
+        if (pid === undefined || !(Number.isFinite(pid) && pid > 0)) {
+            return { cpuVerdict: "unmeasured", cpuPercent: null };
+        }
+        const sample = await sampleProcessTreeCpuPercent(pid, notifyStallCpuSampleMs(), NOTIFY_STALL_CPU_BUSY_FLOOR_PERCENT);
+        if (!sample.measured) {
+            return { cpuVerdict: "unmeasured", cpuPercent: null };
+        }
+        if (sample.busy) {
+            return { cpuVerdict: "busy", cpuPercent: sample.cpuPercent };
+        }
+        return { cpuVerdict: "flat", cpuPercent: sample.cpuPercent };
+    }
+    /**
+     * #2358: one bounded row per busy defer. Not a failure record — the
+     * discrimination succeeded — so it is a plain latency phase; its volume is
+     * bounded by the re-arm cadence of one outstanding write (at most the wedge
+     * cap divided by the budget, ~6 fires at defaults).
+     */
+    logNotifyStallCpuBusy(key, entry, filePath, outstandingMs, verdict, extra = {}) {
+        emitBounded("lsp_notify_stall_cpu_busy", `${key}:${normalizeMapKey(filePath)}`, {
+            type: "phase",
+            durationMs: outstandingMs,
+            metadata: {
+                serverId: entry.info.id,
+                clientKey: key,
+                outstandingMs,
+                cpuPercent: verdict.cpuPercent ?? null,
+                ...extra,
+            },
+        }, {
+            ledgerKind: "lsp-notify-stall-cpu-busy",
+            risingEdgePer: "identity",
+        });
+    }
+    /**
+     * #2358: the patience window a wedged auxiliary write earns.
+     *
+     * max(fixed floor, k x EWMA per-write latency x unacked depth), capped so a
+     * busy-but-never-draining server still respawns within the cap. The EWMA
+     * comes from DRAINED notify barriers (see {@link noteAuxNotifyDrainLatency});
+     * with no history the fixed floor (the pre-#2358 window) stands.
+     */
+    auxNotifyWedgeBudgetMs(key) {
+        let budgetMs = notifyWedgedMs();
+        const ewma = this.auxNotifyDrainLatencyEwma.get(key);
+        if (ewma !== undefined && ewma > 0) {
+            const unacked = this.auxNotifyInflight.get(key)?.unacked ?? 0;
+            budgetMs = Math.max(budgetMs, NOTIFY_WEDGED_EWMA_MULTIPLIER * ewma * unacked);
+        }
+        return Math.min(budgetMs, notifyWedgedCapMs());
+    }
     /**
      * The demotion itself, shared by the #743 consecutive-timeout streak and the
      * #1459 wedged-write rule. Both mean the same thing — this client's input path
      * is not moving — and both need the same teardown.
      */
     demoteForNotifyStall(key, entry, filePath, reason) {
+        // An async verdict belongs to one client generation. Never let a
+        // predecessor's decision delete or cool down its replacement.
+        if (this.state.clients.get(key) !== entry.client)
+            return;
         this.notifyWriteBackpressureStreak.delete(key);
-        this.outstandingAuxNotifyWrites.delete(key);
+        this.releaseOutstandingAuxNotifyWrite(key);
         // #1714: the demoted client is torn down, so its backlog count describes a
         // process that no longer exists. Leaving it would make the replacement start
         // at the ceiling and pay a barrier on its first file.
         this.auxNotifyInflight.delete(key);
         this.state.broken.set(key, Date.now() + BROKEN_BASE_COOLDOWN_MS);
+        this.notifyStallDemotions.set(key, Date.now());
         void entry.client.shutdown().catch(() => { });
         this.state.clients.delete(key);
         this.state.clientSpawnedAt.delete(key);
@@ -1209,6 +1393,87 @@ export class LSPService {
         }
         this.auxNotifyInflight.set(key, { client, unacked: 1 });
     }
+    /**
+     * #2358: fold one DRAINED notify barrier's per-write latency into the
+     * per-key EWMA. A drained round-trip proves the server processed its
+     * `outstanding` backlog after the ping; duration / outstanding is the
+     * per-document service time the single-threaded scanner actually achieves
+     * under load, which is exactly what a busy-server patience window must be
+     * priced from (#2358's evidence: an 855 ms per-answer server with an
+     * 8-write backlog, able to drain in 10-20 s while healthy).
+     */
+    noteAuxNotifyDrainLatency(key, durationMs, outstanding, record) {
+        if (!(outstanding > 0 && durationMs > 0))
+            return;
+        if (record && this.auxNotifyInflight.get(key) !== record)
+            return;
+        const perWriteMs = durationMs / outstanding;
+        const prev = this.auxNotifyDrainLatencyEwma.get(key);
+        this.auxNotifyDrainLatencyEwma.set(key, prev === undefined ? perWriteMs : 0.5 * perWriteMs + 0.5 * prev);
+    }
+    /**
+     * #2358: decide whether a wedged notify write's teardown really fires.
+     *
+     * Before #2358 the breaker killed a server whose write stayed outstanding
+     * past a FIXED window, conflating a dead input path with a busy scanner
+     * draining a burst — the live opengrep kill at #2358's head. The decision
+     * now has two guards, and the record names which one fired:
+     *
+     * - the window is ADAPTIVE — max(fixed floor, k x EWMA per-write latency x
+     *   unacked depth), capped at {@link notifyWedgedCapMs} — so a server that
+     *   historically answers in 855 ms with 8 writes queued earns 13.7 s (k=2),
+     *   not 10 s;
+     * - past the window, the server's process CPU is sampled twice; a BUSY
+     *   server is left alone (the write stays outstanding and the caller re-arms
+     *   this timer), a FLAT or unmeasured one is torn down.
+     *
+     * The hard cap still kills: a busy server that cannot drain inside it is
+     * damaged, and the replacement is the self-heal the breaker exists to
+     * provide.
+     */
+    async decideNotifyStallTeardown(key, entry, filePath, token) {
+        if (this.state.clients.get(key) !== entry.client ||
+            this.outstandingAuxNotifyWrites.get(key) !== token) {
+            throw new Error("stale notify generation");
+        }
+        const outstandingMs = Date.now() - token.startedAt;
+        const armedBudgetMs = token.armedBudgetMs;
+        if (outstandingMs >= notifyWedgedCapMs()) {
+            return {
+                action: "demote",
+                reason: {
+                    outstandingMs,
+                    discriminator: "cap-exceeded",
+                    budgetMs: armedBudgetMs,
+                },
+            };
+        }
+        const verdict = await this.notifyStallCpuVerdict(entry);
+        if (this.state.clients.get(key) !== entry.client ||
+            this.outstandingAuxNotifyWrites.get(key) !== token) {
+            throw new Error("stale notify generation");
+        }
+        if (verdict.cpuVerdict === "busy") {
+            this.logNotifyStallCpuBusy(key, entry, filePath, outstandingMs, verdict, {
+                budgetMs: armedBudgetMs,
+            });
+            return { action: "rearm", budgetMs: this.auxNotifyWedgeBudgetMs(key) };
+        }
+        return {
+            action: "demote",
+            reason: {
+                outstandingMs,
+                discriminator: verdict.cpuVerdict === "unmeasured"
+                    ? "budget-exceeded"
+                    : "budget-exceeded-cpu-flat",
+                budgetMs: armedBudgetMs,
+                ewmaInputMs: this.auxNotifyDrainLatencyEwma.get(key),
+                unackedDepth: this.auxNotifyInflight.get(key)?.unacked ?? 0,
+                cpuVerdict: verdict.cpuVerdict,
+                cpuPercent: verdict.cpuPercent ?? null,
+            },
+        };
+    }
     /**
      * #1714: is this auxiliary already holding as many documents as it may?
      *
@@ -1339,11 +1604,17 @@ export class LSPService {
                     // and the waiter is what latches. A second latch here would be
                     // unreachable, and no test could hold it honest.
                 }
+                // #2358: a DRAINED round-trip is a per-write latency measurement —
+                // the server really processed its backlog — so it feeds the EWMA
+                // the adaptive wedge window is priced from.
+                const durationMs = Date.now() - startedAt;
+                if (drained)
+                    this.noteAuxNotifyDrainLatency(key, durationMs, outstanding, record);
                 this.noteDrainBarrierOutcome(key, entry, filePath, context, {
                     unacked: outstanding,
                     limit,
                     waitMs,
-                    durationMs: Date.now() - startedAt,
+                    durationMs,
                     outcome: drained ? "drained" : "stalled",
                 });
                 return drained;
@@ -1466,7 +1737,7 @@ export class LSPService {
             // respawned) says nothing about this client's stdin — drop it, so a stale
             // entry can never starve a healthy server.
             if (outstanding && outstanding.client !== entry.client) {
-                this.outstandingAuxNotifyWrites.delete(clientKey);
+                this.releaseOutstandingAuxNotifyWrite(clientKey, outstanding);
             }
             else if (outstanding) {
                 const outstandingMs = Date.now() - outstanding.startedAt;
@@ -1503,30 +1774,70 @@ export class LSPService {
                 startedAt: Date.now(),
                 client: entry.client,
                 settled,
-                // A write nothing accepts for the whole wedge window is a dead input
-                // path, not a slow scan. Armed HERE rather than checked by the next
-                // waiter: inside a burst every waiter arrives within one budget, so a
-                // waiter-side check could never see the wedge window elapse and a
-                // wedged scanner was never demoted. Unref'd so it cannot hold a
-                // one-shot host alive, and cleared on release.
-                wedgeTimer: setTimeout(() => {
-                    if (this.outstandingAuxNotifyWrites.get(clientKey) !== token)
-                        return;
-                    this.demoteForNotifyStall(clientKey, entry, filePath, {
-                        outstandingMs: Date.now() - token.startedAt,
-                    });
+                armedBudgetMs: 0,
+                // SAFETY: the handle is a torn-initialized placeholder. It is armed
+                // a beat later in this same atomic claim (no await in between) and
+                // thereafter only ever written by this token's own fire/release
+                // closures, so the placeholder value is never read by anyone.
+                wedgeTimer: undefined,
+                resolveSettled: () => resolveSettled?.(),
+            };
+            // A write nothing accepts for the whole wedge window is a dead input
+            // path, not a slow scan. Armed HERE rather than checked by the next
+            // waiter: inside a burst every waiter arrives within one budget, so a
+            // waiter-side check could never see the wedge window elapse and a
+            // wedged scanner was never demoted. Unref'd so it cannot hold a
+            // one-shot host alive, and cleared on release.
+            //
+            // #2358: the window itself is now ADAPTIVE (issue's `max(fixed,
+            // k x EWMA per-answer latency x unacked depth)`, capped), and when it
+            // fires the server's process CPU is sampled before the kill — a busy
+            // server is left alone and the timer re-arms, so a scanner draining a
+            // burst is never killed by construction. Every fire re-checks the
+            // token identity after its awaits, so a release or a concurrent
+            // demotion that lands mid-sample aborts the decision.
+            const fireWedge = async () => {
+                if (this.outstandingAuxNotifyWrites.get(clientKey) !== token ||
+                    this.state.clients.get(clientKey) !== entry.client) {
+                    this.releaseOutstandingAuxNotifyWrite(clientKey, token);
+                    return;
+                }
+                let decision;
+                try {
+                    decision = await this.decideNotifyStallTeardown(clientKey, entry, filePath, token);
+                }
+                catch {
+                    // A failed decision must not strand the outstanding write or the
+                    // waiter: fall back to the pre-#2358 demote-at-budget teardown.
+                    decision = {
+                        action: "demote",
+                        reason: {
+                            outstandingMs: Date.now() - token.startedAt,
+                            discriminator: "budget-exceeded",
+                            budgetMs: token.armedBudgetMs,
+                        },
+                    };
+                }
+                if (this.outstandingAuxNotifyWrites.get(clientKey) !== token ||
+                    this.state.clients.get(clientKey) !== entry.client) {
+                    this.releaseOutstandingAuxNotifyWrite(clientKey, token);
+                    return;
+                }
+                if (decision.action === "demote") {
+                    this.demoteForNotifyStall(clientKey, entry, filePath, decision.reason);
                     resolveSettled?.();
-                }, notifyWedgedMs()),
+                    return;
+                }
+                token.wedgeTimer = setTimeout(() => void fireWedge(), decision.budgetMs);
+                token.wedgeTimer.unref?.();
             };
+            token.armedBudgetMs = this.auxNotifyWedgeBudgetMs(clientKey);
+            token.wedgeTimer = setTimeout(() => void fireWedge(), token.armedBudgetMs);
             token.wedgeTimer.unref?.();
             this.outstandingAuxNotifyWrites.set(clientKey, token);
             return {
                 release: () => {
-                    clearTimeout(token.wedgeTimer);
-                    if (this.outstandingAuxNotifyWrites.get(clientKey) === token) {
-                        this.outstandingAuxNotifyWrites.delete(clientKey);
-                    }
-                    resolveSettled?.();
+                    this.releaseOutstandingAuxNotifyWrite(clientKey, token);
                 },
             };
         }
@@ -1607,6 +1918,30 @@ export class LSPService {
         return entries.sort((a, b) => (priority.get(a.serverId) ?? Number.MAX_SAFE_INTEGER) -
             (priority.get(b.serverId) ?? Number.MAX_SAFE_INTEGER));
     }
+    /**
+     * Documents currently open on any live client rooted at or under `cwd`
+     * (#2430), as normalized path keys.
+     *
+     * The third contributor to the observational mutation net's tracked-file
+     * set, alongside the read-guard's read/write set and the widget's diagnostic
+     * files. It is pure in-memory enumeration — no spawn, no open, no stat —
+     * and it is deliberately capped by the caller rather than here, because the
+     * cap belongs to the sweep's budget, not to the pool's bookkeeping.
+     */
+    getOpenDocumentPaths(cwd) {
+        const paths = new Set();
+        for (const { client } of this.activeClientsForCwd(cwd)) {
+            try {
+                for (const filePath of client.openDocumentPaths?.() ?? [])
+                    paths.add(filePath);
+            }
+            catch {
+                // A client torn down mid-enumeration contributes nothing; the sweep
+                // is advisory and must never break on a dying server.
+            }
+        }
+        return [...paths];
+    }
     /**
      * Get or create LSP client for a file
      * Prevents duplicate client creation via in-flight promise tracking
@@ -1617,14 +1952,76 @@ export class LSPService {
         // Primary selection considers language servers only — auxiliary servers
         // (opengrep, …) attach alongside the primary and are never chosen as it.
         const servers = getServersForFileWithConfig(filePath).filter((s) => s.role !== "auxiliary");
-        const serverWaitOverrideMs = servers.reduce((max, server) => Math.max(max, server.clientWaitTimeoutMs ?? 0), 0);
+        // #2525: candidate roots are resolved LAZILY, and at most once per call.
+        // They are deliberately NOT hoisted: `NearestRoot` (clients/lsp/server.ts)
+        // caches successful hits but never negatives, so a fallback that cannot
+        // root here — DenoServer (`fallbackFor: "typescript"`, gated on
+        // deno.json(c)) in a project with no deno.json — re-walks to the
+        // filesystem root on EVERY call, by design, so that a deno.json
+        // scaffolded mid-session is picked up without a restart. Hoisting would
+        // charge that walk to every touch of every .ts file in every non-Deno
+        // project. The sequential trial loop below needs no roots of its own
+        // (`ensureClientForServer` resolves and bails at `!root` before any spawn
+        // work), so a served touch — the hot path — resolves nothing extra at
+        // all. Only the branches that EMIT a candidate list ask, and all of them
+        // are cold paths.
+        const rootMemo = new Map();
+        /**
+         * Split the candidates into the ones that could actually have been waited
+         * on and the ones that never had a spawn slot. A record's subject must be
+         * its producer (#1550) — the #2524 shape.
+         *
+         * #2525 round 3 (F3): no SHIPPED `server.root` rejects today — every one
+         * bottoms out in `markerExists`, which only ever resolves `false` on a
+         * miss — so this was reasoned "removed by construction". A reviewer probe
+         * disproved that: a `root()` that rejects makes this `Promise.all` reject,
+         * which throws out of `getClientForFile` itself (the caller never gets
+         * `undefined` back, and `lsp_client_wait_timeout` is never emitted). A
+         * per-server catch degrades that candidate to unrooted instead of taking
+         * the whole partition down — the same "producer" the memo already knows
+         * (a failed root resolution never got a client either), now WITH the
+         * failure reason so the record says why, not just that.
+         */
+        const partitionCandidates = async () => {
+            const resolved = await Promise.all(servers.map(async (server) => {
+                try {
+                    return {
+                        server,
+                        root: await this.resolveServerRootOnce(server, filePath, rootMemo),
+                        reason: undefined,
+                    };
+                }
+                catch (error) {
+                    return {
+                        server,
+                        root: undefined,
+                        reason: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            }));
+            const unrootedReasons = {};
+            for (const entry of resolved) {
+                if (entry.root === undefined && entry.reason !== undefined) {
+                    unrootedReasons[entry.server.id] = entry.reason;
+                }
+            }
+            return {
+                rooted: resolved
+                    .filter((entry) => entry.root !== undefined)
+                    .map(({ server, root }) => ({ server, root })),
+                unrootedIds: resolved
+                    .filter((entry) => entry.root === undefined)
+                    .map((entry) => entry.server.id),
+                unrootedReasons,
+            };
+        };
         // hardCapMs is a caller-imposed ceiling (e.g. pipeline budget) that
         // prevents tool_result from blocking the TUI for the full LSP cold-start
         // window. When no server config sets a wait (serverWaitOverrideMs = 0),
         // hardCapMs is used directly — Math.min(0, cap) = 0 would otherwise
         // take the no-timeout branch and block indefinitely (e.g. pyright, which
         // has no clientWaitTimeoutMs but can take 30s to initialize on cold start).
-        const serverBaseMs = Math.max(maxWaitMs ?? 0, serverWaitOverrideMs);
+        const serverBaseMs = primaryServerWaitFloorMs(filePath, maxWaitMs);
         const effectiveMaxWaitMs = hardCapMs !== undefined
             ? serverBaseMs > 0
                 ? Math.min(serverBaseMs, hardCapMs)
@@ -1655,7 +2052,10 @@ export class LSPService {
             // joined it, instead of pinning a starter label on every joiner.
             let erroredServerId;
             let erroredOutcome;
-            // Try each matching server
+            // Try each matching server in registration order.
+            // `ensureClientForServer` resolves the root itself and returns before
+            // any spawn work when there is none, so an unrooted fallback costs
+            // this loop one already-memoized resolution and no spawn slot.
             for (const server of servers) {
                 // A box, not a `let`: control-flow analysis cannot see the callback
                 // write and would narrow a plain local to its initializer.
@@ -1664,7 +2064,7 @@ export class LSPService {
                 };
                 const spawned = await this.ensureClientForServer(filePath, server, resolvedRoots, noteSpawnInFlight, (reported) => {
                     acquisition.outcome = reported;
-                });
+                }, rootMemo);
                 if (spawned) {
                     logLatency({
                         type: "phase",
@@ -1710,8 +2110,16 @@ export class LSPService {
                     },
                 });
             }
+            // #2525: reuse the roots the trial loop above already resolved rather
+            // than re-walking with the RAW `server.root`. Two reasons: the raw
+            // call skips the ceiling/session-root gates, so this dedupe key could
+            // disagree with the identity the acquisition path actually used; and
+            // on the unserved path — the only path that reaches here — every
+            // unrooted candidate would pay a second full walk to the filesystem
+            // root, on every touch, before the `unavailableLogged` dedupe even
+            // looked at it.
             const unavailable = (await Promise.all(servers.map(async (server) => {
-                const root = await server.root(filePath);
+                const root = await this.resolveServerRootOnce(server, filePath, rootMemo);
                 return {
                     server,
                     key: `${server.id}:${root ? normalizeMapKey(root) : "<unresolved>"}`,
@@ -1767,11 +2175,13 @@ export class LSPService {
             // `inFlight` is cleared in ensureClientForServer's finally block, so a
             // settled acquisition can still be present here. Re-read the published
             // clients at the decision point; a usable client outranks the sentinel.
-            for (const server of servers) {
-                const root = await this.resolveServerRoot(server, filePath);
-                const client = root
-                    ? this.state.clients.get(`${server.id}:${normalizeMapKey(root)}`)
-                    : undefined;
+            // #2525: this is a cold path, so it is where the roots get resolved —
+            // once, memoized with the trial loop's own resolutions. An unrooted
+            // fallback can never have a client keyed under its (non-existent)
+            // root, so it is neither probed here nor named in the record below.
+            const { rooted, unrootedIds, unrootedReasons } = await partitionCandidates();
+            for (const { server, root } of rooted) {
+                const client = this.state.clients.get(`${server.id}:${normalizeMapKey(root)}`);
                 if (client?.isAlive())
                     return { client, info: server };
             }
@@ -1783,16 +2193,46 @@ export class LSPService {
                 durationMs: 0,
                 metadata: {
                     maxWaitMs: effectiveMaxWaitMs,
-                    serverIds: servers.map((server) => server.id),
+                    serverIds: rooted.map(({ server }) => server.id),
+                    unrootedCandidates: {
+                        count: unrootedIds.length,
+                        ids: unrootedIds,
+                        ...(Object.keys(unrootedReasons).length > 0
+                            ? { reasons: unrootedReasons }
+                            : {}),
+                    },
                     reason: "budget_skipped_known_slow",
                 },
             });
             return undefined;
         }
         if (waitResult === timeoutSentinel) {
+            // #2525: likewise a cold path — resolve here, not up front.
+            //
+            // #2525 round 3 (L2): `partitionCandidates` does UNCACHED negative
+            // root walks (`NearestRoot` never caches misses, by design — see the
+            // comment above `rootMemo`) and this branch only reaches it AFTER
+            // `effectiveMaxWaitMs` has already elapsed. Measured by the reviewer:
+            // 2.06ms native, ~150ms on the #462 slow-FS profile — unbounded on top
+            // of a budget whose entire contract is "return within the cap". Bound
+            // it with a small ceiling of its own (a quarter of the caller's hard
+            // cap when one was given, capped at 250ms) rather than leaving it the
+            // one piece of async work in this function with no bound at all
+            // (the "async work needs both bounds" shape — here there is no
+            // per-call abort signal to race, only the timer bound applies).
+            const partitionBudgetMs = hardCapMs !== undefined ? Math.min(250, hardCapMs / 4) : 250;
+            const partitioned = await withDeadline(partitionCandidates(), {
+                ms: partitionBudgetMs,
+                onTimeout: "undefined",
+            });
+            const { rooted, unrootedIds, unrootedReasons } = partitioned ?? {
+                rooted: [],
+                unrootedIds: [],
+                unrootedReasons: {},
+            };
             // Snapshot known client health — scan by serverId prefix (no root needed)
             const knownHealth = [...this.state.clients.entries()]
-                .filter(([k]) => servers.some((s) => k.startsWith(`${s.id}:`)))
+                .filter(([k]) => rooted.some(({ server }) => k.startsWith(`${server.id}:`)))
                 .map(([k, c]) => ({
                 serverId: k.split(":")[0],
                 alive: c.isAlive(),
@@ -1805,9 +2245,23 @@ export class LSPService {
                 durationMs: effectiveMaxWaitMs,
                 metadata: {
                     maxWaitMs: effectiveMaxWaitMs,
-                    serverIds: servers.map((s) => s.id),
+                    // `serverIds` names the ROOTED pool the timeout record reports
+                    // against, not "servers this call actually waited on" — the
+                    // sequential trial loop can time out having reached only the
+                    // first of several rooted candidates (case 2 in the regression
+                    // test pins both `["typescript","deno"]` even though the loop
+                    // never got past `typescript`).
+                    serverIds: rooted.map(({ server }) => server.id),
+                    unrootedCandidates: {
+                        count: unrootedIds.length,
+                        ids: unrootedIds,
+                        ...(Object.keys(unrootedReasons).length > 0
+                            ? { reasons: unrootedReasons }
+                            : {}),
+                    },
                     // servers absent from knownHealth were never spawned or are still spawning
                     knownClientHealth: knownHealth,
+                    ...(partitioned === undefined ? { partition: "timed-out" } : {}),
                 },
             });
             return undefined;
@@ -1815,8 +2269,10 @@ export class LSPService {
         return waitResult;
     }
     /**
-     * Get or create ALL LSP clients that can serve a file.
-     * Used for diagnostics aggregation across complementary servers.
+     * Get or create all complementary LSP clients that can serve a file. Alternate
+     * language servers marked with `fallbackFor` remain sequential fallbacks: an
+     * aggregate diagnostics pass must not launch them beside a working preferred
+     * server merely because it requested `clientScope: "all"`.
      */
     async getClientsForFile(filePath, excludeServerIds, resolvedRoots) {
         const allServers = getServersForFileWithConfig(filePath);
@@ -1825,28 +2281,59 @@ export class LSPService {
             : allServers;
         if (servers.length === 0)
             return { clients: [], serverCountAttempted: 0 };
-        // Count servers with a valid root as "attempted" — extension-only matches
-        // that fail the root check are not real spawn attempts.
-        const roots = await Promise.all(servers.map((s) => this.resolveServerRoot(s, filePath)));
-        const serverCountAttempted = roots.filter(Boolean).length;
-        const spawned = await Promise.all(servers.map((server) => this.ensureClientForServer(filePath, server, resolvedRoots)));
-        return {
-            clients: spawned.filter((entry) => Boolean(entry)),
-            serverCountAttempted,
+        // Resolve once to keep the attempted count tied to servers with a real root.
+        const rootedServers = (await Promise.all(servers.map(async (server) => ({
+            server,
+            root: await this.resolveServerRoot(server, filePath),
+        })))).filter((entry) => entry.root !== undefined);
+        let serverCountAttempted = 0;
+        const acquisitions = new Map();
+        const acquire = (server) => {
+            serverCountAttempted += 1;
+            return this.ensureClientForServer(filePath, server, resolvedRoots);
         };
+        // Start complementary servers immediately. An alternate waits only for its
+        // own preferred server, not for unrelated scanners, and starts if that server
+        // declines. Registry order makes chained fallbacks deterministic.
+        for (const { server } of rootedServers) {
+            const preferred = server.fallbackFor
+                ? acquisitions.get(server.fallbackFor)
+                : undefined;
+            const acquisition = preferred
+                ? preferred.then((entry) => entry === undefined ? acquire(server) : undefined)
+                : acquire(server);
+            acquisitions.set(server.id, acquisition);
+        }
+        const results = await Promise.all(acquisitions.values());
+        const clients = results.filter((entry) => entry !== undefined);
+        return { clients, serverCountAttempted };
     }
     /**
      * Spawn/get the AUXILIARY clients for a file (role:"auxiliary") restricted to
      * the enabled set. These attach alongside the primary on the with-auxiliary
      * diagnostics path (cross-cutting scanners like opengrep).
      */
-    async getAuxiliaryClientsForFile(filePath, enabledIds, onOutcome) {
+    async getAuxiliaryClientsForFile(filePath, enabledIds, onOutcome, maxWaitMs, signal, hook) {
         if (this.checkDestroyed() || enabledIds.size === 0)
             return [];
         const servers = getServersForFileWithConfig(filePath).filter((s) => s.role === "auxiliary" && enabledIds.has(s.id));
         if (servers.length === 0)
             return [];
-        const spawned = await Promise.all(servers.map((server) => this.ensureClientForServer(filePath, server, undefined, undefined, (reported) => onOutcome?.(server.id, reported))));
+        const rootMemo = new Map();
+        const effectiveSignal = signal ?? getAmbientAbortSignal();
+        const effectiveHook = hook ?? "tool_result_edit";
+        const spawned = await Promise.all(servers.map(async (server) => {
+            const acquisition = this.ensureClientForServer(filePath, server, undefined, undefined, (reported) => onOutcome?.(server.id, reported), rootMemo);
+            if (!maxWaitMs || maxWaitMs <= 0) {
+                return acquisition;
+            }
+            return bounded(acquisition, {
+                ms: maxWaitMs,
+                signal: effectiveSignal,
+                hook: effectiveHook,
+                label: `auxiliary-spawn:${server.id}`,
+            });
+        }));
         return spawned.filter((entry) => Boolean(entry));
     }
     /**
@@ -1928,9 +2415,11 @@ export class LSPService {
      * the Gate-B readiness check, this NEVER creates or warms a client — it only
      * resolves each requested server's root and reads the already-connected
      * client's cached diagnostics for `filePath`. Servers with no live client
-     * are simply absent from the returned map. A live client is present only
-     * when its per-file cache entry exists; its timestamp distinguishes a
-     * published clean result from no publication.
+     * are absent unless notify-stall teardown marked that generation as
+     * replaceable; that status carries the demotion timestamp so turn-end late
+     * coverage can correlate each pair to the removed generation. A live
+     * client is present even when its per-file cache entry is empty; its
+     * timestamp distinguishes a published clean result from no publication.
      */
     async readCachedDiagnosticsForServers(filePath, serverIds) {
         const out = new Map();
@@ -1944,8 +2433,20 @@ export class LSPService {
                 continue;
             const key = `${server.id}:${normalizeMapKey(root)}`;
             const client = this.state.clients.get(key);
-            if (!client?.isAlive())
+            if (!client?.isAlive()) {
+                const demotedAt = this.notifyStallDemotions.get(key);
+                if (demotedAt !== undefined) {
+                    out.set(server.id, {
+                        diags: [],
+                        notifyStallDemoted: true,
+                        demotedAt,
+                    });
+                }
                 continue;
+            }
+            // A replacement is live again. The old generation's marker no longer
+            // describes this client and must not make a later absence look transient.
+            this.notifyStallDemotions.delete(key);
             const entry = client.getAllDiagnostics().get(normalizeMapKey(filePath));
             out.set(server.id, {
                 diags: entry?.diags ?? [],
@@ -2156,7 +2657,29 @@ export class LSPService {
     noteSpawnVerdict(key, verdict) {
         this.lastSpawnVerdict.set(key, verdict);
     }
-    async ensureClientForServer(filePath, server, resolvedRoots, onSpawnInFlight, onOutcome) {
+    /**
+     * {@link resolveServerRoot}, memoized against a caller-owned map so one
+     * acquisition asks a given server for its root at most once (#2525).
+     *
+     * Resolution is cheap exactly when it SUCCEEDS: `NearestRoot` caches hits,
+     * but deliberately never caches negatives (so a marker scaffolded
+     * mid-session is picked up without a restart). An unrooted candidate
+     * therefore re-walks to the filesystem root on every call, which is why the
+     * acquisition path and the records it emits must share one resolution
+     * instead of each taking their own. Without a `memo` this is a plain
+     * passthrough, for callers that have no acquisition to share with.
+     */
+    resolveServerRootOnce(server, filePath, memo) {
+        if (!memo)
+            return this.resolveServerRoot(server, filePath);
+        const pending = memo.get(server.id);
+        if (pending !== undefined)
+            return pending;
+        const started = this.resolveServerRoot(server, filePath);
+        memo.set(server.id, started);
+        return started;
+    }
+    async ensureClientForServer(filePath, server, resolvedRoots, onSpawnInFlight, onOutcome, rootMemo) {
         const handoff = this.generationHandoff;
         if (handoff) {
             await handoff;
@@ -2166,7 +2689,7 @@ export class LSPService {
             if (this.checkDestroyed())
                 return undefined;
         }
-        const root = await this.resolveServerRoot(server, filePath);
+        const root = await this.resolveServerRootOnce(server, filePath, rootMemo);
         if (!root || this.checkDestroyed())
             return undefined;
         if (server.role !== "auxiliary") {
@@ -2269,6 +2792,7 @@ export class LSPService {
                     intentional: wasIntentional,
                 },
             });
+            this.releaseOutstandingAuxNotifyWrite(key);
             try {
                 await existing.shutdown();
             }
@@ -2618,6 +3142,9 @@ export class LSPService {
                     diagnosticProviderKind: "unavailable",
                 };
             this.state.clients.set(key, client);
+            // #2356: this generation is the replacement the late-coverage probe was
+            // waiting for. Clear the retired-generation marker before any later probe.
+            this.notifyStallDemotions.delete(key);
             this.unavailableLogged.delete(key);
             // #1934 review F1: a success retires the previous verdict, so the map
             // never outlives the attempts it describes.
@@ -2800,10 +3327,27 @@ export class LSPService {
         else if (clientScope === "with-auxiliary") {
             // Primary language server + the enabled cross-cutting auxiliaries
             // (opengrep, …). The aggregation layer merges/dedups their diagnostics.
+            const auxStartedAt = Date.now();
             const [entry, aux] = await Promise.all([
                 this.getClientForFile(filePath, options.maxClientWaitMs, undefined, resolvedPrimaryRoots, waitSkipReasons),
-                this.getAuxiliaryClientsForFile(filePath, new Set(options.auxiliaryServerIds ?? []), noteColdAuxiliary),
+                this.getAuxiliaryClientsForFile(filePath, new Set(options.auxiliaryServerIds ?? []), noteColdAuxiliary, options.maxClientWaitMs, undefined, options.hook),
             ]);
+            const auxDurationMs = Date.now() - auxStartedAt;
+            if (options.auxiliaryServerIds && options.auxiliaryServerIds.length > 0) {
+                logLatency({
+                    type: "phase",
+                    phase: "auxiliary_readiness",
+                    filePath: normalizedPath,
+                    durationMs: auxDurationMs,
+                    metadata: {
+                        serverIds: aux.map((s) => s.info.id),
+                        attemptedCount: options.auxiliaryServerIds.length,
+                        readyCount: aux.length,
+                        coldServerIds: [...coldAuxiliaryServerIds],
+                        source,
+                    },
+                });
+            }
             spawned = entry ? [entry, ...aux] : aux;
             serverCountAttempted = spawned.length;
         }
@@ -3008,14 +3552,26 @@ export class LSPService {
             if (!notifySkipped) {
                 const budget = notifyWriteBudgetMs();
                 // #1459: how long a queued auxiliary may wait for its resync slot. Bounded
-                // by the write budget AND by whatever the caller already declared it is
-                // willing to spend on this touch (`maxClientWaitMs` — cascade's cold
-                // snapshot passes 1000ms), minus what the client wait above already spent.
+                // by the write budget and by the effective primary wait floor, minus what
+                // which includes the caller's `maxClientWaitMs` and any primary
+                // server `clientWaitTimeoutMs` override. The elapsed client wait is
+                // subtracted below.
                 // A flat write-budget wait would tax a caller that asked for less than one
                 // budget in total. Non-positive means "no time left to queue": the server
                 // is reported as uncovered immediately.
+                //
+                // #2239: "what the caller already declared" is `primaryServerWaitFloorMs`,
+                // not the raw `options.maxClientWaitMs` — the SAME floor `getClientForFile`
+                // races the primary spawn against. A cold primary configured with its own
+                // `clientWaitTimeoutMs` (Ruby 30s, and the #2233 Bash/JSON/Vue/Svelte/Prisma
+                // overrides) is allowed to run past the caller's flat budget, and did just
+                // that by the time this line runs — charging the subtraction against the
+                // flat value alone always went negative and clamped to zero. The outer
+                // `Math.min(budget, …)` is unchanged, so this raises what "already spent"
+                // is measured against without widening the wait beyond one write budget.
                 const queueWaitMs = options.maxClientWaitMs !== undefined
-                    ? Math.min(budget, Math.max(0, options.maxClientWaitMs - (Date.now() - startedAt)))
+                    ? Math.min(budget, Math.max(0, primaryServerWaitFloorMs(filePath, options.maxClientWaitMs) -
+                        (Date.now() - startedAt)))
                     : budget;
                 await Promise.all(spawned.map(async (entry) => {
                     // #743: this server already has this content from a recent touch
@@ -3103,10 +3659,13 @@ export class LSPService {
                                 // streak outright, so only the late case retracts. A landing
                                 // past the WEDGE window keeps its strike: at that point the
                                 // stall was long enough that #743's demotion is the honest
-                                // verdict, not a latency artifact.
+                                // verdict, not a latency artifact. #2358: the wedge window
+                                // is the adaptive one the timer itself arms with, so a
+                                // write a BUSY server would have been left alone for also
+                                // retracts its strike instead of accruing a ladder charge.
                                 const outstandingMs = Date.now() - writeStartedAt;
                                 if (outstandingMs > budget &&
-                                    outstandingMs <= notifyWedgedMs()) {
+                                    outstandingMs <= this.auxNotifyWedgeBudgetMs(clientKey)) {
                                     this.retractNotifyWriteBackpressure(clientKey, entry.info.id, filePath, outstandingMs, client);
                                 }
                             }, release);
@@ -4398,9 +4957,7 @@ export class LSPService {
                         reason: reasons.join(", ") || "scanner coverage gap",
                     });
                 }
-                logLatency({
-                    type: "phase",
-                    phase: "lsp_scanner_coverage_gap",
+                emitBounded("lsp_scanner_coverage_gap", `${source}:${normalizedPath}`, {
                     filePath: normalizedPath,
                     durationMs: Date.now() - startedAt,
                     metadata: {
@@ -4409,10 +4966,10 @@ export class LSPService {
                         ...(brokenSkippedServerIds.length > 0 && {
                             brokenSkippedServerIds,
                         }),
-                        // #1586: the deferrals this touch is actually uncovered for. The raw
+                        // #1586: the deferrals this touch is actually uncovered for. The
                         // gate action keeps its own record in `lsp_notify_resync_deferred`;
-                        // this row exists to prove a blackout, and a scanner already bound to
-                        // these bytes is not one.
+                        // this row exists to prove a blackout, and a scanner already bound
+                        // to these bytes is not one.
                         ...(uncoveredDeferredServerIds.length > 0 && {
                             deferredResyncServerIds: uncoveredDeferredServerIds,
                         }),
@@ -5841,6 +6398,23 @@ export class LSPService {
         // never proved it can answer diagnostics — that's a failed warm-up. A
         // server with an unresolvable key never spawns here, so it can't fail this
         // way and is excluded (never skipped by the caller for this file).
+        // #2525: same split the readiness logic above already makes — `keys[i]`
+        // is `undefined` exactly when the server resolves no key for this file,
+        // i.e. it will never spawn here (DenoServer without a deno.json). The
+        // `lsp_sweep_warmup_*` records must not claim to have warmed it. Free:
+        // `keys` is already resolved, so this costs no filesystem work.
+        const rootedServerIds = [];
+        const unrootedServerIds = [];
+        for (let i = 0; i < servers.length; i++) {
+            if (keys[i] !== undefined)
+                rootedServerIds.push(servers[i].id);
+            else
+                unrootedServerIds.push(servers[i].id);
+        }
+        const unrootedCandidates = {
+            count: unrootedServerIds.length,
+            ids: unrootedServerIds,
+        };
         const stillColdServerIds = () => {
             const cold = [];
             for (let i = 0; i < servers.length; i++) {
@@ -5860,7 +6434,12 @@ export class LSPService {
                 phase: "lsp_sweep_warmup_start",
                 filePath: representativeFile,
                 durationMs: 0,
-                metadata: { serverIds: servers.map((s) => s.id), timeoutMs, attempt },
+                metadata: {
+                    serverIds: rootedServerIds,
+                    unrootedCandidates,
+                    timeoutMs,
+                    attempt,
+                },
             });
             const warmupAttempt = this.touchFile(representativeFile, content, {
                 diagnostics: "document",
@@ -5910,7 +6489,8 @@ export class LSPService {
                 filePath: representativeFile,
                 durationMs: Date.now() - startedAt,
                 metadata: {
-                    serverIds: servers.map((s) => s.id),
+                    serverIds: rootedServerIds,
+                    unrootedCandidates,
                     timeoutMs,
                     attempt,
                     coldServerIds,
@@ -6935,6 +7515,9 @@ export class LSPService {
         if (this.checkDestroyed())
             return;
         this.isDestroyed = true;
+        for (const [key, token] of this.outstandingAuxNotifyWrites) {
+            this.releaseOutstandingAuxNotifyWrite(key, token);
+        }
         for (const key of this.typeScriptIdleTimers.keys()) {
             this.clearTypeScriptIdleTimer(key);
         }
@@ -6987,7 +7570,15 @@ export class LSPService {
         // #1459: every gated client is gone, so no outstanding-write record can
         // describe a live one. The gate's identity check already neutralises a stale
         // entry; clearing keeps the map honest rather than relying on that.
-        this.outstandingAuxNotifyWrites.clear();
+        for (const [key, token] of this.outstandingAuxNotifyWrites) {
+            this.releaseOutstandingAuxNotifyWrite(key, token);
+        }
+        this.notifyStallDemotions.clear();
+        // #2358: same reasoning — a per-write latency estimate belongs to a client
+        // generation, and every client is gone. `session_start` reaches this
+        // through the service reset, so the adaptive wedge window re-arms with
+        // the session rather than being priced by a previous one's throughput.
+        this.auxNotifyDrainLatencyEwma.clear();
         // #1714: same reasoning — a backlog count belongs to a client generation,
         // and every client is gone. `session_start` reaches this through the service
         // reset, so the pacing state re-arms with the session rather than living for
@@ -7189,6 +7780,20 @@ export async function notifyExternalFileChange(filePath, type) {
     return getLSPService().notifyExternalFileChange(filePath, type);
 }
 export function resetLSPService(options = {}) {
+    // #2504 review round 2 (F3): whatever the retiring service was still being
+    // asked for off-hook must stop HERE, before any teardown and before the
+    // `!retiringService` early return below (a `session_start` reset with no
+    // live service must still retire a loop the previous session armed). This
+    // is the one choke point every lifecycle path goes through —
+    // `session_shutdown`, `session_start`, and the idle reset — so the
+    // deferred actionable-warnings pull cannot open another file against a
+    // dying service, cannot re-spawn one after the idle reset, and cannot be
+    // mid-`openFile` when the loop closes (#234). Aborting spawns nothing.
+    abortDeferredLspWork(`lsp service reset: ${options.reason ?? "unspecified"}`);
+    // Invalidate availability publication started by the retiring service before
+    // any asynchronous teardown. The launch seam checks this generation after
+    // every managed lookup, install, and process launch (#2351).
+    resetLspLaunchAvailabilityGeneration();
     // A new session must get its own classic-tsserver-repair attempt: the
     // guard is a process-lifetime flag (see resetClassicTsRepairGuard), so a
     // repair that failed transiently in an earlier session must not stay