pi-lens 3.8.70 → 3.8.71

package/dist/clients/lsp/index.js

@@ -15,6 +15,7 @@ import { isTestMode } from "../env-utils.js";
 import { getGlobalPiLensDir, getProjectIgnoreMatcher, isExcludedDirName, } from "../file-utils.js";
 import { recordLsp } from "../widget-state.js";
 import { applyAuxiliarySuppressions } from "../dispatch/auxiliary-lsp.js";
+import { detectFileRole } from "../file-role.js";
 import { logLatency } from "../latency-logger.js";
 import { withDeadline } from "../deadline-utils.js";
 import { normalizeMapKey, uriToPath } from "../path-utils.js";
@@ -25,6 +26,9 @@ import { LSP_SERVERS, isDirectLspCommandTemporarilyUnavailable, } from "./server
 import { getStrategy } from "./server-strategies.js";
 import { raceToCompletion } from "./aggregation.js";
 import { applyWorkspaceEdit, mergeWorkspaceTextEditsByPriority, summarizeWorkspaceEdit, } from "./edits.js";
+import { buildScopeKey, createWorkspaceDiagnosticsCacheContext, } from "./workspace-diagnostics-cache.js";
+import { attemptTsserverSyncDiagnostics, } from "./tsserver-sync.js";
+import { classifyCascadeWaitTier } from "./cascade-tier.js";
 // --- Init override helpers ---
 /**
  * Recursively merges `override` onto `base`. Override wins on leaf conflicts
@@ -96,6 +100,42 @@ function readEnvDiagnosticsWaitMs() {
         return undefined;
     return parsed;
 }
+/**
+ * #707: grace delay before the racing tsserver sync clean-confirm fires on a
+ * tier-3 silent primary. Short enough to beat the full push-wait budget by a
+ * wide margin (~300ms grace + sync RTT vs ~1000ms budget), long enough to give
+ * a genuinely dirty file's push a head start — a push that arrives within the
+ * grace costs zero extra requests. Read at call time (not memoized) so tests
+ * and users can tune without a rebuild.
+ */
+function readTsserverSyncGraceMs() {
+    const raw = process.env.PI_LENS_TSSERVER_SYNC_GRACE_MS;
+    if (raw === undefined)
+        return 300;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 300;
+    return parsed;
+}
+/**
+ * Read the `PI_LENS_AUX_GRACE_MS` env override at call time (not module
+ * load time) so tests can set it per-case. Controls how long auxiliary-role
+ * promises (opengrep, ast-grep, zizmor, …) are waited after all primary-role
+ * promises have settled in both getDiagnostics (raceToCompletion) and the
+ * touchFile push wait. Default 500ms — conservative enough to include
+ * auxiliaries that are nearly done while not blocking the primary result.
+ * Returns undefined when the var is absent (caller falls back to the
+ * raceToCompletion default of 500ms, keeping the two in sync).
+ */
+function readEnvAuxGraceMs() {
+    const raw = process.env.PI_LENS_AUX_GRACE_MS;
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return undefined;
+    return parsed;
+}
 const DIAGNOSTICS_SEMANTIC_SETTLE_THRESHOLD_MS = Math.max(0, Number.parseInt(process.env.PI_LENS_LSP_DIAGNOSTICS_SEMANTIC_THRESHOLD_MS ?? "250", 10) || 250);
 const DIAGNOSTICS_SEMANTIC_SETTLE_WAIT_MS = Math.max(0, Number.parseInt(process.env.PI_LENS_LSP_DIAGNOSTICS_SEMANTIC_SETTLE_MS ?? "400", 10) || 400);
 // Once the fastest client has diagnostics, remaining clients get this window before
@@ -295,6 +335,10 @@ function getMaxWorkspaceDiagnosticFiles() {
 async function collectWorkspaceDiagnosticFiles(root, maxFiles = getMaxWorkspaceDiagnosticFiles(), signal) {
     const files = [];
     const ignoreMatcher = getProjectIgnoreMatcher(root);
+    // #703: prime the tracked-files set once before the walk so a tracked file
+    // matching a `.gitignore`/global pattern still gets its workspace
+    // diagnostics pulled. Fail-open on no-git/spawn failure.
+    await ignoreMatcher.ensureTrackedIndex();
     async function walk(current) {
         if (signal?.aborted || files.length >= maxFiles)
             return;
@@ -733,6 +777,19 @@ export class LSPService {
         recordLsp(server.id, root, "spawn_start");
         try {
             const spawned = await server.spawn(root, { allowInstall });
+            // Guard 1: service was shut down while we were waiting for the spawn.
+            // Kill the raw process — no LSPClient exists yet — and bail out without
+            // marking the key broken (this is not a server failure).
+            if (this.isDestroyed) {
+                try {
+                    spawned?.process?.process?.kill();
+                }
+                catch {
+                    // pi-lens-ignore: missing-error-propagation — best-effort kill on aborted spawn
+                }
+                logSessionStart(`lsp spawn ${server.id}: aborted (service shut down mid-spawn)`);
+                return undefined;
+            }
             if (!spawned) {
                 logSessionStart(`lsp spawn ${server.id}: unavailable (${Date.now() - startedAt}ms)`);
                 recordLsp(server.id, root, "spawn_failed", Date.now() - startedAt);
@@ -766,6 +823,13 @@ export class LSPService {
                 initializeTimeoutMs: server.initializeTimeoutMs,
                 launchVariant: spawned.launchVariant,
             });
+            // Guard 2: service was shut down while we were completing the initialize
+            // handshake. Shut down the live client best-effort and do not register it.
+            if (this.isDestroyed) {
+                client.shutdown({ fast: true }).catch(() => { });
+                logSessionStart(`lsp spawn ${server.id}: aborted (service shut down mid-initialize)`);
+                return undefined;
+            }
             const wsDiag = typeof client.getWorkspaceDiagnosticsSupport === "function"
                 ? client.getWorkspaceDiagnosticsSupport()
                 : {
@@ -940,6 +1004,17 @@ export class LSPService {
             }
         }
         let diagnosticsTimedOut = false;
+        // R8 (#714): server ids of aux-role servers whose push wait was cut off by
+        // the aux grace window. Undefined when no aux was cut off (primary-only
+        // paths never set this). Logged in lsp_touch_file metadata.
+        let auxCutOffServerIds;
+        // #707: tsserver sync clean-confirm state. `tsserverSyncEligible` is the
+        // full gate (evaluated once, before the wait); `tsserverSyncConfirmed`
+        // holds the sync commands' answer when the racing confirm won the wait
+        // (undefined = the race didn't produce an answer; the end-of-wait
+        // fallback below may still fill it in on a timed-out empty result).
+        let tsserverSyncEligible = false;
+        let tsserverSyncConfirmed = undefined;
         if (diagnosticsMode !== "none") {
             // Resolution: env wins so users can tune the cap without rebuilding.
             // Otherwise, on the single-server hot path (primary scope), use that
@@ -1008,6 +1083,13 @@ export class LSPService {
                             Math.min(300, strategyWait);
                 }
                 if (callerCap !== undefined) {
+                    // #669: `ensureWarmForSweep`'s cold-server warm-up wants its cap
+                    // to act as a FLOOR (give it at least this much, possibly more
+                    // if the strategy already wants more) rather than the normal
+                    // ceiling — see `warmupOverride` doc on `LSPTouchFileOptions`.
+                    if (options.warmupOverride) {
+                        return Math.max(callerCap, strategyWait > 0 ? strategyWait : 0);
+                    }
                     return Math.min(callerCap, strategyWait > 0 ? strategyWait : callerCap);
                 }
                 return strategyWait > 0 ? strategyWait : modeFloor;
@@ -1030,8 +1112,51 @@ export class LSPService {
             }
             // Detection deadline = the slowest individual server's budget.
             const timeoutMs = Math.max(0, ...spawned.map((e) => timeoutFor(e.client.serverId)));
+            // #707: evaluate the tsserver sync clean-confirm gate BEFORE the wait
+            // starts. Cheap synchronous gates first (notify succeeded, collecting,
+            // primary scope, strategy marked silentOnClean — only classic
+            // typescript-language-server carries that flag today), then the live
+            // capability-snapshot tier classification (`classifyCascadeWaitTier`,
+            // which also excludes native-ts7 via `launchVariant`). Non-typescript
+            // and pull-capable servers fail the synchronous `silentOnClean` gate and
+            // pay ZERO extra work — not even the snapshot read.
+            if (!notifyWriteTimedOut &&
+                options.collectDiagnostics === true &&
+                clientScope === "primary" &&
+                spawned.length === 1 &&
+                getStrategy(spawned[0].client.serverId).silentOnClean === true) {
+                try {
+                    const snapshots = await this.getCapabilitySnapshots(filePath);
+                    tsserverSyncEligible =
+                        classifyCascadeWaitTier(this, filePath, snapshots) ===
+                            "tier3-silent";
+                }
+                catch {
+                    // Fail-safe: ineligible — today's full wait, no sync attempt.
+                }
+            }
             const waitStartedAt = Date.now();
-            await Promise.all(spawned.map((entry) => {
+            // R8 (#714): on the with-auxiliary path, apply a bounded aux grace so a
+            // slow auxiliary no longer holds the push wait to its own deadline.
+            // Primary waits resolve on their own per-server budget; once ALL primaries
+            // have settled the auxiliaries get at most auxGraceMs before we proceed.
+            // Primary-only and "all"/"primary" scopes are completely unaffected —
+            // they fall through to the original Promise.all path below.
+            //
+            // "Primary" here = a server whose LSPServerInfo.role is not "auxiliary".
+            // In the with-auxiliary spawn list, `getClientForFile` returns the
+            // language-primary entry first and `getAuxiliaryClientsForFile` appends
+            // the rest — but we use info.role rather than position so the logic is
+            // correct even if ordering shifts in the future.
+            //
+            // The #707 tsserver sync race operates exclusively on single-server
+            // primary-scope touches (guarded by `clientScope === "primary" &&
+            // spawned.length === 1`), so there is NO interaction with this path.
+            const hasTouchAuxiliaries = clientScope === "with-auxiliary" &&
+                spawned.some((e) => e.info.role === "auxiliary");
+            // Per-server wait promises (each already bounded by its own
+            // perServerTimeout — unchanged from before R8).
+            const perServerWaits = spawned.map((entry) => {
                 const serverTimeout = timeoutFor(entry.client.serverId);
                 const baseline = diagnosticBaselines.get(entry.client);
                 const wait = !notifySkipped && Number.isFinite(baseline)
@@ -1040,12 +1165,154 @@ export class LSPService {
                     })
                     : entry.client.waitForDiagnostics(filePath, serverTimeout);
                 return wait.catch(() => undefined);
-            }));
+            });
+            // The push wait — same per-server budget composition as before #707;
+            // only the awaiting changed (assigned so it can be raced below).
+            let pushWaitSettled = false;
+            const pushWait = hasTouchAuxiliaries
+                ? (() => {
+                    // Primary waits: all non-auxiliary servers.
+                    const primaryWaits = perServerWaits.filter((_, i) => spawned[i].info.role !== "auxiliary");
+                    // Aux waits: auxiliary servers (advisory).
+                    const auxWaits = perServerWaits
+                        .map((p, i) => spawned[i].info.role === "auxiliary"
+                        ? { promise: p, serverId: spawned[i].info.id }
+                        : null)
+                        .filter((x) => x !== null);
+                    const auxGraceMs = readEnvAuxGraceMs() ?? 500;
+                    // After all primaries settle, give auxiliaries at most auxGraceMs.
+                    // Late aux results are dropped from the wait (advisory only — they
+                    // land in the client cache and surface on the next edit); aux servers
+                    // that did answer within the grace are included automatically since
+                    // their waitForDiagnostics already resolved. The cut-off server ids
+                    // are logged in the latency metadata (lsp_touch_file phase, field
+                    // `auxCutOffServerIds`).
+                    return Promise.all(primaryWaits).then(async () => {
+                        if (auxWaits.length === 0)
+                            return;
+                        const auxTimeout = new Promise((resolve) => {
+                            const t = setTimeout(() => resolve("timeout"), auxGraceMs);
+                            if (typeof t === "object" && "unref" in t)
+                                t.unref?.();
+                        });
+                        const auxAll = Promise.all(auxWaits.map((a) => a.promise)).then(() => "done");
+                        const outcome = await Promise.race([auxAll, auxTimeout]);
+                        if (outcome === "timeout") {
+                            // Record which auxiliaries did NOT finish in time.
+                            const unfinished = [];
+                            for (const a of auxWaits) {
+                                let done = false;
+                                // Check synchronously if already resolved by racing against
+                                // a resolved promise.
+                                await Promise.race([
+                                    a.promise.then(() => {
+                                        done = true;
+                                    }),
+                                    Promise.resolve(),
+                                ]);
+                                if (!done)
+                                    unfinished.push(a.serverId);
+                            }
+                            if (unfinished.length > 0)
+                                auxCutOffServerIds = unfinished;
+                        }
+                    });
+                })()
+                : Promise.all(perServerWaits).then(() => { });
+            pushWait.then(() => {
+                pushWaitSettled = true;
+            });
+            if (tsserverSyncEligible) {
+                // #707 racing variant: rather than burning the full push-wait budget
+                // on a silent-on-clean server (which by definition never answers on a
+                // clean file), race the push wait against a grace-delayed sync
+                // confirm. The grace (default 300ms, PI_LENS_TSSERVER_SYNC_GRACE_MS)
+                // gives a genuinely dirty file's push a head start: if diagnostics
+                // arrive before the grace elapses, the sync request never goes out —
+                // zero new latency or requests on the push-answers path.
+                //
+                // Race semantics:
+                //   - sync answers first → that's the confirmed result (clean OR
+                //     dirty — the sync commands return the file's real syntactic +
+                //     semantic state, so a dirty-file win is still correct and its
+                //     findings are surfaced, never discarded).
+                //   - push settles first → push wins; a still-in-flight sync outcome
+                //     is discarded (the racer checks `pushWaitSettled` after the
+                //     call returns and drops its own result).
+                //   - sync unavailable/fails → the racer parks on a never-resolving
+                //     promise so the race is decided by the push wait's own budget,
+                //     exactly today's behavior (the end-of-wait fallback below still
+                //     gets its shot on a timed-out empty result).
+                // The racer never rejects (every failure path is caught), so the
+                // losing promise can never surface as an unhandled rejection.
+                const graceMs = readTsserverSyncGraceMs();
+                const primaryClient = spawned[0].client;
+                // Resolves with the sync commands' diagnostics when the confirm
+                // succeeds; parks on a never-resolving promise on EVERY other path
+                // (push already answered, sync unavailable/failed, push won while
+                // in flight) so the race is then decided by the push wait's own
+                // budget — exactly today's behavior.
+                const syncRacer = (async () => {
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(resolve, graceMs);
+                        timer.unref?.();
+                    });
+                    // Push already answered (settled, or published diagnostics that
+                    // its wait is about to settle on) — nothing to confirm, no sync
+                    // request goes out.
+                    if (pushWaitSettled ||
+                        primaryClient.getDiagnostics(filePath).length > 0) {
+                        return new Promise(() => { });
+                    }
+                    try {
+                        const result = await attemptTsserverSyncDiagnostics(filePath, this);
+                        if (result === undefined || pushWaitSettled) {
+                            // Sync unavailable/failed, or push won while the sync call
+                            // was in flight — drop the sync outcome and let the push
+                            // wait decide the race.
+                            return new Promise(() => { });
+                        }
+                        return result;
+                    }
+                    catch {
+                        return new Promise(() => { });
+                    }
+                })();
+                const raceOutcome = await Promise.race([
+                    pushWait.then(() => undefined),
+                    syncRacer,
+                ]);
+                if (raceOutcome !== undefined) {
+                    tsserverSyncConfirmed = raceOutcome;
+                }
+            }
+            else {
+                await pushWait;
+            }
             const waitedMs = Date.now() - waitStartedAt;
-            // Within ~20 ms of the configured budget we treat it as a timeout;
-            // the LSP didn't beat the cap. Diagnostics that arrive late still
-            // land in the client's cache and surface on the next edit.
-            if (waitedMs + 20 >= timeoutMs) {
+            if (tsserverSyncConfirmed !== undefined) {
+                // #707: the racing sync confirm won — a definitive answer well under
+                // the push-wait budget. Not a timeout, not inconclusive.
+                logLatency({
+                    type: "phase",
+                    phase: "lsp_tsserver_sync_confirm",
+                    filePath: normalizedPath,
+                    durationMs: waitedMs,
+                    metadata: {
+                        source,
+                        clientScope,
+                        diagnosticsMode,
+                        mode: "race",
+                        confirmedDiagnosticCount: tsserverSyncConfirmed.length,
+                        budgetMs: timeoutMs,
+                        savedVsBudgetMs: Math.max(0, timeoutMs - waitedMs),
+                    },
+                });
+            }
+            else if (waitedMs + 20 >= timeoutMs) {
+                // Within ~20 ms of the configured budget we treat it as a timeout;
+                // the LSP didn't beat the cap. Diagnostics that arrive late still
+                // land in the client's cache and surface on the next edit.
                 diagnosticsTimedOut = true;
                 logLatency({
                     type: "phase",
@@ -1061,9 +1328,63 @@ export class LSPService {
                 });
             }
         }
-        const collected = options.collectDiagnostics
-            ? mergeLspDiagnostics(spawned.flatMap((entry) => entry.client.getDiagnostics(filePath)))
+        // #707: when the racing sync confirm won the wait, its answer IS the
+        // collected result — the file's real syntactic + semantic state straight
+        // from tsserver (clean = [], dirty = real findings that a silentOnClean
+        // server had computed but never published). Otherwise merge the push
+        // diagnostics from the client cache as always.
+        let collected = options.collectDiagnostics
+            ? tsserverSyncConfirmed !== undefined
+                ? mergeLspDiagnostics(tsserverSyncConfirmed)
+                : mergeLspDiagnostics(spawned.flatMap((entry) => entry.client.getDiagnostics(filePath)))
             : undefined;
+        // #707 end-of-wait fallback: when the racing confirm did NOT decide the
+        // wait (sync unavailable/failed mid-race, or push resolved as a bare
+        // timeout) and the wait timed out with an empty result on an eligible
+        // touch, give the sync clean-confirm one last shot before reporting
+        // inconclusive. `tsserverSyncEligible` already encodes every gate (notify
+        // succeeded, collecting, primary scope, tier3-silent classic typescript —
+        // native-ts7 excluded by `classifyCascadeWaitTier`). If the sync call
+        // answers (even with an empty body, which is a confirmed clean), we use
+        // those diagnostics as the confirmed result and clear the
+        // `diagnosticsTimedOut` flag so the touch is no longer treated as
+        // inconclusive. Sync diagnostics on a dirty file are surfaced, not
+        // discarded. If the sync call fails or is unavailable, we fall through to
+        // today's behavior: `inconclusive` = true, `collected` unchanged. This
+        // turns "unconfirmed after ~1000ms" into "confirmed at ~wait+sync-RTT"
+        // even when the race path couldn't answer.
+        if (diagnosticsTimedOut &&
+            tsserverSyncEligible &&
+            collected !== undefined &&
+            collected.length === 0) {
+            try {
+                const syncResult = await attemptTsserverSyncDiagnostics(filePath, this);
+                if (syncResult !== undefined) {
+                    // Sync answered — confirmed result (clean or with diagnostics).
+                    // Clear the timed-out flag so the touch is no longer inconclusive.
+                    diagnosticsTimedOut = false;
+                    collected = syncResult.length > 0
+                        ? mergeLspDiagnostics(syncResult)
+                        : [];
+                    logLatency({
+                        type: "phase",
+                        phase: "lsp_tsserver_sync_confirm",
+                        filePath: normalizedPath,
+                        durationMs: Date.now() - startedAt,
+                        metadata: {
+                            source,
+                            clientScope,
+                            diagnosticsMode,
+                            mode: "end-of-wait",
+                            confirmedDiagnosticCount: collected.length,
+                        },
+                    });
+                }
+            }
+            catch {
+                // Any failure here falls through to today's inconclusive behavior.
+            }
+        }
         // A touch is inconclusive when EITHER the notify write or the
         // diagnostics wait hit their deadline for ANY of the spawned servers
         // (these flags are touch-wide, covering the whole `Promise.all` over
@@ -1138,6 +1459,11 @@ export class LSPService {
                 notifyWriteTimedOut,
                 diagnosticsTimedOut,
                 inconclusive,
+                // R8 (#714): server ids of auxiliaries whose push wait was cut off by
+                // the aux grace window (primary settled clean + aux timed out in grace).
+                // Absent when no aux was cut off. These servers' diagnostics are
+                // advisory-only and will surface on the next edit from their cache.
+                ...(auxCutOffServerIds !== undefined && { auxCutOffServerIds }),
             },
         });
         return collected ?? [];
@@ -1245,12 +1571,25 @@ export class LSPService {
         // Document mode: 0ms grace — return as soon as any client has results.
         // Full mode: 400ms grace — wait a bit for other clients to catch up.
         const graceMs = diagnosticsMode === "document" ? 0 : EARLY_UNBLOCK_GRACE_MS;
+        // R8 (#714): per-promise role descriptors so raceToCompletion can apply
+        // a bounded aux grace once all primary-role promises have settled.
+        // Servers with role:"auxiliary" (opengrep, ast-grep, zizmor, …) get at
+        // most PI_LENS_AUX_GRACE_MS (default 500ms) after the primary settles;
+        // late arrivals are dropped (advisory only — they land in the client
+        // cache and surface on the next edit). Primary-only callers have no
+        // auxiliary descriptors, so this path is never entered and there is
+        // zero behavior change for the single-server hot path.
+        const diagDescriptors = spawned.map((entry) => ({
+            role: entry.info.role === "auxiliary" ? "auxiliary" : "primary",
+        }));
         // Result-aware racing: trigger early-unblock when any client has results,
         // OR when a seedFirstPush server returns (its first push is authoritative
         // even when empty — waiting longer yields nothing more).
         const perServer = await raceToCompletion(clientWaits, (results) => results.some((r) => r.diagnosticCount > 0 || getStrategy(r.serverId).seedFirstPush), {
             timeoutMs: Math.max(...spawned.map((entry) => getStrategy(entry.info.id).aggregateWaitMs)),
             graceMs,
+            descriptors: diagDescriptors,
+            auxGraceMs: readEnvAuxGraceMs(),
         });
         // Fill in any slots that timed out before producing results.
         const earlyUnblockedCount = spawned.length - perServer.length;
@@ -1736,6 +2075,12 @@ export class LSPService {
             source: "lsp_sweep_warmup",
             maxClientWaitMs: timeoutMs,
             maxDiagnosticsWaitMs: timeoutMs,
+            // #669: the caller's cap here is the warm-up budget for a genuinely
+            // COLD server — it must act as a floor, not the usual ceiling, or
+            // `perServerTimeout` silently shrinks it to the strategy's normal
+            // warm-state `aggregateWaitMs` (e.g. 1000ms for typescript) instead
+            // of the requested 20000ms.
+            warmupOverride: true,
         });
         await (options.signal
             ? Promise.race([
@@ -1793,6 +2138,43 @@ export class LSPService {
         let completed = 0;
         let timedOutFiles = 0;
         let lastHeartbeat = Date.now();
+        // #671: reuse the last CONFIRMED per-file result instead of re-touching
+        // every file through the language server(s) again when nothing relevant
+        // changed since the last sweep. `createWorkspaceDiagnosticsCacheContext`
+        // (`workspace-diagnostics-cache.ts`) is shared with `tools/lsp-
+        // diagnostics.ts`'s batch/directory sweep so a file swept by either tool
+        // benefits the other's next sweep under the SAME `scopeKey` — see that
+        // module's doc comment for the invalidation rules (own-mtime +
+        // best-effort cross-file dependency staleness) and why `scopeKey` exists
+        // (this sweep's `excludeServerIds` differs from that tool's).
+        const workspaceDiagnosticsCacheCtx = createWorkspaceDiagnosticsCacheContext(root);
+        const workspaceSweepScopeKey = buildScopeKey("all", [
+            ...WORKSPACE_SWEEP_EXCLUDED_SERVER_IDS,
+        ]);
+        const cachedResults = [];
+        const filesToTouch = [];
+        for (const filePath of files) {
+            const cached = workspaceDiagnosticsCacheCtx.lookup(filePath, workspaceSweepScopeKey);
+            if (cached) {
+                cachedResults.push({
+                    filePath,
+                    diagnostics: cached.diagnostics,
+                    count: cached.count,
+                });
+            }
+            else {
+                filesToTouch.push(filePath);
+            }
+        }
+        completed = cachedResults.length;
+        if (cachedResults.length > 0) {
+            options.onProgress?.(completed, files.length);
+        }
+        // Per-file scan mtime captured as each file completes below, so a
+        // confirmed fresh result can be written back into the cache with the
+        // mtime it was ACTUALLY scanned at (not re-stat'd after the fact, which
+        // could race a concurrent edit).
+        const scannedMtimeByFile = new Map();
         // Group files by their primary language server (#387, extracted as
         // `groupFilesByPrimaryServer` for #631). tsserver — and most servers — is
         // single-threaded per project: N concurrent touches to ONE server don't
@@ -1803,7 +2185,9 @@ export class LSPService {
         // in-flight touch each) and parallelize ACROSS servers — real parallelism
         // where it exists (a mixed TS+Python repo runs both), no flooding where it
         // doesn't. Capped so a many-language monorepo can't spawn unbounded groups.
-        const groups = groupFilesByPrimaryServer(files);
+        // Only files that failed the cache-freshness check above go through this
+        // (and the touch loop below) at all.
+        const groups = groupFilesByPrimaryServer(filesToTouch);
         // #645: shared across every file/group in THIS sweep — lets a
         // `workspaceIndexing`-strategy server (marksman) pay its full
         // aggregateWaitMs budget only for the first file that touches it,
@@ -1828,6 +2212,8 @@ export class LSPService {
             durationMs: 0,
             metadata: {
                 fileCount: files.length,
+                cacheHits: cachedResults.length,
+                filesToTouch: filesToTouch.length,
                 maxFiles,
                 perFileMs,
                 serverGroups: groups.length,
@@ -1927,6 +2313,23 @@ export class LSPService {
             try {
                 const content = contentCache.get(filePath) ??
                     (await nodeFs.promises.readFile(filePath, "utf-8"));
+                // #671: captured alongside the read, ahead of the (possibly slow)
+                // touchFile wait below, so the cache entry records the mtime this
+                // file actually had AT scan time — not a later re-stat that could
+                // race a concurrent edit and silently mis-date the entry. Deliberately
+                // synchronous (not `nodeFs.promises.stat`): this loop is timing-
+                // sensitive (its opens must land inside `WatchedFilesQueue`'s 100ms
+                // debounce window — see workspace-diagnostics-sweep-batch-open.test.ts
+                // / -preopen-chunk.test.ts), and a blocking `statSync` costs a few
+                // microseconds with no extra event-loop tick, where an awaited
+                // promise would insert one.
+                try {
+                    scannedMtimeByFile.set(filePath, nodeFs.statSync(filePath).mtimeMs);
+                }
+                catch {
+                    // Best-effort: a failed stat here just means this file won't be
+                    // eligible for caching below (no entry gets written for it).
+                }
                 // onTimeout:"undefined" so a hung file yields no diagnostics and the
                 // worker moves on; a real touchFile rejection still propagates to the
                 // catch below and is recorded as an error.
@@ -1961,8 +2364,17 @@ export class LSPService {
                 // `.inconclusive` flag, already read above) so a `lens_diagnostics
                 // mode=full` sweep suppresses the same findings the per-edit dispatch
                 // runner does, instead of only the latter honoring it.
+                // #692: also honor a profile's `skipTestFiles` gate (e.g. ast-grep,
+                // #687/#688) — those PRs added the gate only to the per-edit merge
+                // loop (`clients/dispatch/runners/lsp.ts`), so a `mode=full` sweep
+                // re-surfaced every ast-grep finding on `*.test.ts` files wholesale,
+                // duplicating what the per-edit path already suppresses. `content`
+                // was already read above for this file, so `detectFileRole` gets the
+                // higher-accuracy content-aware classification at no extra cost.
                 const filteredDiagnostics = diagnostics
-                    ? applyAuxiliarySuppressions(diagnostics, content)
+                    ? applyAuxiliarySuppressions(diagnostics, content, {
+                        fileRole: detectFileRole(filePath, content),
+                    })
                     : diagnostics;
                 results.push({
                     filePath,
@@ -2017,8 +2429,19 @@ export class LSPService {
             if (workspacePullEnabled && !group.multiServer) {
                 const pulled = await this.tryWorkspacePull(group.files, perFileMs);
                 if (pulled) {
-                    for (const result of pulled)
+                    for (const result of pulled) {
                         results.push(result);
+                        // #671: a pull result is always confirmed (see
+                        // `tryWorkspacePull`'s doc comment), so it's cache-eligible
+                        // too — best-effort stat since the pull already resolved the
+                        // diagnostics for this file some time ago.
+                        try {
+                            scannedMtimeByFile.set(result.filePath, nodeFs.statSync(result.filePath).mtimeMs);
+                        }
+                        catch {
+                            // Not cache-eligible without a confirmed mtime.
+                        }
+                    }
                     completed += group.files.length;
                     options.onProgress?.(completed, files.length);
                     return;
@@ -2067,6 +2490,7 @@ export class LSPService {
             durationMs: Date.now() - startedAt,
             metadata: {
                 filesChecked: files.length,
+                cacheHits: cachedResults.length,
                 diagnosticCount: results.reduce((sum, result) => sum + (result?.count ?? 0), 0),
                 serverGroups: groups.length,
                 concurrency: groupWorkers,
@@ -2075,7 +2499,25 @@ export class LSPService {
                 aborted: signal?.aborted ?? false,
             },
         });
-        return results.filter(Boolean);
+        // #671: record every CONFIRMED fresh result (`!timedOut && !error`) back
+        // into the cache, keyed by the mtime it was actually scanned at
+        // (`scannedMtimeByFile`, captured per-file above), then persist once.
+        // Deliberately survives an aborted/partial sweep — whatever completed
+        // before the abort is still real, confirmed work and shouldn't be thrown
+        // away; files that never got a confirmed result (including ones an abort
+        // cut off before `processFile` ran) are simply absent from
+        // `scannedMtimeByFile` and are skipped, leaving any pre-existing cache
+        // entry for them exactly as `createWorkspaceDiagnosticsCacheContext`
+        // loaded it (already-stale entries stay unreachable via `lookup`'s own
+        // freshness check; nothing here needs to explicitly evict them).
+        for (const result of results) {
+            const scannedAt = scannedMtimeByFile.get(result.filePath);
+            if (result.error || result.timedOut || scannedAt === undefined)
+                continue;
+            workspaceDiagnosticsCacheCtx.record(result.filePath, workspaceSweepScopeKey, result.diagnostics, scannedAt);
+        }
+        workspaceDiagnosticsCacheCtx.persist();
+        return [...cachedResults, ...results].filter(Boolean);
     }
     /**
      * #387 Item 2: one `workspace/diagnostic` pull covering a whole server group,
@@ -2184,8 +2626,38 @@ export class LSPService {
         if (this.checkDestroyed())
             return;
         this.isDestroyed = true;
-        // Cancel any in-flight spawns
-        this.state.inFlight.clear();
+        // Belt-and-braces: wait for any in-flight spawns so that Guard 1/2 in
+        // spawnClient can observe isDestroyed and clean up. Skip on the
+        // process-exiting path — the event loop is closing and we must not block.
+        if (!options.processExiting && this.state.inFlight.size > 0) {
+            const pending = Array.from(this.state.inFlight.values());
+            this.state.inFlight.clear();
+            const settled = await Promise.allSettled(pending);
+            for (const result of settled) {
+                if (result.status === "fulfilled" && result.value?.client) {
+                    result.value.client.shutdown({ fast: true }).catch(() => { });
+                }
+            }
+        }
+        else {
+            this.state.inFlight.clear();
+        }
+        // Count alive clients BEFORE tearing them down — gives a meaningful
+        // snapshot of what was released by this reset (post-teardown the count
+        // would always be zero, which is useless for root-cause analysis).
+        const aliveClients = this.getAliveClientCount();
+        logLatency({
+            type: "phase",
+            phase: "lsp_service_reset",
+            filePath: "",
+            durationMs: 0,
+            metadata: {
+                reason: options.reason ?? null,
+                aliveClients,
+                fast: !!options.fast,
+                processExiting: !!options.processExiting,
+            },
+        });
         for (const [_key, client] of this.state.clients) {
             try {
                 await client.shutdown(options);