@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts

@@ -2,10 +2,27 @@
 // biome-ignore-all lint/style/noExcessiveLinesPerFile: LspManager stays cohesive; recovery and sync helpers are split into manager-*.ts modules.
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { type CodeQueryResult, unavailableCodeQuery } from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type CodeQueryResult,
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
 import * as projectRoots from "@mrclrchtr/supi-core/project";
-import { LspClient } from "../client/client.ts";
+import * as ts from "typescript";
+import {
+  LspClient,
+  type LspClientLifecycleTransitionKind,
+  RECOVERY_CLIENT_STARTUP_BOUND_MS,
+  withTimeout,
+} from "../client/client.ts";
+import type { ClientDiagnosticSnapshot } from "../client/client-document-state.ts";
+
+export { RECOVERY_CLIENT_STARTUP_BOUND_MS } from "../client/client.ts";
+
 import { getServerForFile } from "../config/config.ts";
+import { getFileScopeDecision } from "../config/tsconfig-scope.ts";
 import type {
   DetectedProjectServer,
   Diagnostic,
@@ -22,6 +39,17 @@ import {
   createOutstandingDiagnosticSummary,
   relativeFilePathFromUri,
 } from "../diagnostics/diagnostic-summary.ts";
+import {
+  type DiagnosticEvidenceDocument,
+  type DiagnosticEvidenceSummary,
+  summarizeDiagnosticEvidence,
+} from "../diagnostics/evidence.ts";
+import { raceRequestControl } from "../session/readiness.ts";
+import type {
+  ScopeDecisionEntry,
+  ScopeDecisionSummary,
+  WorkspaceDiagnosticReport,
+} from "../session/runtime-diagnostics.ts";
 import {
   displayRelativeFilePath,
   formatCoverageSummaryText,
@@ -30,7 +58,7 @@ import {
   normalizeRelevantPaths,
   shouldIgnoreLspPath,
 } from "../summary.ts";
-import { commandExists, resolveSessionPath } from "../utils.ts";
+import { commandExists, resolveSessionPath, uriToFile } from "../utils.ts";
 import {
   closeFileAcrossClients,
   pruneMissingFilesFromClients,
@@ -55,7 +83,10 @@ import type {
   OutstandingDiagnosticSummaryEntry,
   ServerStatus,
 } from "./manager-types.ts";
-import { recoverWorkspaceDiagnostics as recoverWorkspaceDiagnosticsImpl } from "./manager-workspace-recovery.ts";
+import {
+  recoverWorkspaceDiagnostics as recoverWorkspaceDiagnosticsImpl,
+  type WorkspaceRecoveryResult,
+} from "./manager-workspace-recovery.ts";
 import {
   collectWorkspaceSymbols,
   findWorkspaceSymbolWarmTargets,
@@ -66,6 +97,35 @@ import {
 
 type UnavailableReason = "missing-command" | "start-failed" | "runtime-error";
 
+/** Maximum tracked-file entries retained in one scope-decision telemetry summary. */
+const SCOPE_DECISION_MAX_ENTRIES = 24;
+
+interface ScopeDecisionAccumulator {
+  entries: ScopeDecisionEntry[];
+  counts: ScopeDecisionSummary["counts"];
+  basisCounts: Record<string, number>;
+}
+
+function accumulateScopeDecision(
+  accumulator: ScopeDecisionAccumulator,
+  file: string,
+  decision: ReturnType<typeof getFileScopeDecision>,
+): void {
+  const statusKey =
+    decision.status === "no-config"
+      ? "noConfig"
+      : decision.status === "out-of-tree"
+        ? "outOfTree"
+        : decision.status;
+  accumulator.counts[statusKey]++;
+  if (decision.basis) {
+    accumulator.basisCounts[decision.basis] = (accumulator.basisCounts[decision.basis] ?? 0) + 1;
+  }
+  if (accumulator.entries.length < SCOPE_DECISION_MAX_ENTRIES) {
+    accumulator.entries.push({ file, status: decision.status, basis: decision.basis });
+  }
+}
+
 type FileRoute = {
   serverName: string;
   serverConfig: ServerConfig;
@@ -73,6 +133,24 @@ type FileRoute = {
   key: string;
 };
 
+type ClientRestartResult = {
+  key: string;
+  serverName: string;
+  files: string[];
+  restarted: boolean;
+};
+
+export type ManagerLifecycleTransitionKind = LspClientLifecycleTransitionKind | "recovery";
+
+/** Package-internal aggregate lifecycle snapshot for the runtime controller. */
+export interface ManagerLifecycleTransition {
+  readonly kind: ManagerLifecycleTransitionKind;
+  readonly semanticReady: boolean;
+  readonly projectServers: readonly ProjectServerInfo[];
+}
+
+type ManagerLifecycleListener = (transition: ManagerLifecycleTransition) => void;
+
 // ── LspManager ────────────────────────────────────────────────────────
 export class LspManager {
   /** Active clients keyed by "serverName:root" */
@@ -83,10 +161,16 @@ export class LspManager {
   private commandAvailability = new Map<string, boolean>();
   /** Guards against concurrent client creation for the same server:root key */
   private pendingStarts = new Map<string, Promise<LspClient | null>>();
+  /** Monotonic ownership generation for each replaceable client route. */
+  private clientGenerations = new Map<string, number>();
   /** Preferred project roots discovered by proactive scan or lazy startup */
   private knownRoots = new Map<string, string[]>();
   /** User-configured gitignore-style exclude patterns */
   private excludePatterns: string[] = [];
+  /** Monotonic workspace invalidation generation advanced by each invalidation event. */
+  private invalidationEpoch = 0;
+  /** Invalidation generation in which each route last received a recovery restart. */
+  private recoveryRestartEpochs = new Map<string, number>();
   /** Project roots already warmed for workspace-symbol queries. */
   private warmedWorkspaceSymbolProjects = new Set<string>();
   /** Project roots whose semantic state was warmed with a readiness probe. */
@@ -96,6 +180,7 @@ export class LspManager {
   constructor(
     private readonly config: LspConfig,
     private readonly cwd: string,
+    private readonly onLifecycleTransition?: ManagerLifecycleListener,
   ) {}
   getCwd(): string {
     return this.cwd;
@@ -152,6 +237,15 @@ export class LspManager {
 
     return reason;
   }
+
+  /** Return the open document version without starting a server. */
+  getOpenDocumentVersion(filePath: string): number | null {
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
+    return (
+      this.getExistingClientForFile(resolvedPath)?.getOpenDocumentVersion(resolvedPath) ?? null
+    );
+  }
+
   /** Get or create an LSP client for the given file. */
   async getClientForFile(filePath: string): Promise<LspClient | null> {
     const route = this.resolveFileRoute(filePath);
@@ -194,6 +288,53 @@ export class LspManager {
     }
   }
 
+  private createClient(
+    serverName: string,
+    serverConfig: ServerConfig,
+    root: string,
+    key: string,
+  ): LspClient {
+    const generation = (this.clientGenerations.get(key) ?? 0) + 1;
+    this.clientGenerations.set(key, generation);
+    let client: LspClient;
+    client = new LspClient(
+      serverName,
+      serverConfig,
+      root,
+      (kind) => {
+        this.handleClientLifecycle(key, generation, client, kind);
+      },
+      this.cwd,
+    );
+    return client;
+  }
+
+  private handleClientLifecycle(
+    key: string,
+    generation: number,
+    client: LspClient,
+    kind: LspClientLifecycleTransitionKind,
+  ): void {
+    if (this.clientGenerations.get(key) !== generation) return;
+    if (this.clients.get(key) !== client) return;
+    const aggregateKind =
+      kind === "readiness" && generation > 1 && client.ready ? "recovery" : kind;
+    this.publishLifecycle(aggregateKind);
+  }
+
+  private publishLifecycle(kind: ManagerLifecycleTransitionKind): void {
+    if (!this.onLifecycleTransition) return;
+    const projectServers = this.getKnownProjectServers([]);
+    const semanticReady = projectServers.some(
+      (server) => server.status === "running" && server.ready,
+    );
+    try {
+      this.onLifecycleTransition({ kind, semanticReady, projectServers });
+    } catch {
+      // Runtime lifecycle consumers must not alter manager behavior.
+    }
+  }
+
   /**
    * Perform the actual server start — extracted so the public method can
    * deduplicate via pendingStarts without wrapping the entire body.
@@ -211,7 +352,7 @@ export class LspManager {
     }
 
     // Spawn new client
-    const client = new LspClient(serverName, serverConfig, root);
+    const client = this.createClient(serverName, serverConfig, root, key);
     this.clearWarmedWorkspaceSymbolProjects(serverName, root);
     this.clearWarmedSemanticProjects(serverName, root);
     this.clearPendingWarmProbes(serverName, root);
@@ -247,33 +388,51 @@ export class LspManager {
     return route ? (this.clients.get(route.key) ?? null) : null;
   }
 
-  /** Restart the clients that own the supplied file paths, if any are active. */
-  async restartClientsForFiles(filePaths: string[]): Promise<string[]> {
-    const restarted: string[] = [];
+  /**
+   * Restart the clients that own the supplied file paths, if any are active.
+   *
+   * Each route restarts at most once per invalidation generation. Pass
+   * `pushOnly` to restrict restarts to clients without pull diagnostics.
+   * The loop observes request cancellation between route restarts.
+   */
+  async restartClientsForFiles(
+    filePaths: string[],
+    options?: { pushOnly?: boolean; control?: CodeRequestControl },
+  ): Promise<ClientRestartResult[]> {
+    const restarted: ClientRestartResult[] = [];
     const seen = new Set<string>();
 
     for (const filePath of filePaths) {
       const client = this.getExistingClientForFile(filePath);
       if (!client) continue;
+      if (options?.pushOnly && client.hasDiagnosticProvider) continue;
 
       const key = clientKey(client.name, client.root);
       if (seen.has(key)) continue;
       seen.add(key);
+      if (this.recoveryRestartEpochs.get(key) === this.invalidationEpoch) continue;
 
-      if (await this.restartClient(client)) {
-        restarted.push(key);
-      }
+      // Observe cancellation between route restarts so a cancelled pass does
+      // not keep restarting further clients.
+      throwIfCodeRequestInterrupted(options?.control);
+      const result = await this.restartClient(client);
+      this.recoveryRestartEpochs.set(key, this.invalidationEpoch);
+      restarted.push({ key, serverName: client.name, ...result });
     }
 
     return restarted;
   }
 
-  private async restartClient(client: LspClient): Promise<boolean> {
+  private async restartClient(client: LspClient): Promise<{ files: string[]; restarted: boolean }> {
     const key = clientKey(client.name, client.root);
     const serverConfig = this.config.servers[client.name];
-    if (!serverConfig) return false;
+    if (!serverConfig) return { files: [], restarted: false };
 
     const openFiles = client.openFiles;
+    const trackedDiagnosticFiles = client
+      .getDiagnosticSnapshot()
+      .documents.map((document) => uriToFile(document.uri));
+    const files = [...new Set([...openFiles, ...trackedDiagnosticFiles])];
     try {
       await client.shutdown();
     } catch {
@@ -286,25 +445,37 @@ export class LspManager {
     this.clearWarmedSemanticProjects(client.name, client.root);
     this.clearPendingWarmProbes(client.name, client.root);
 
-    const replacement = new LspClient(client.name, serverConfig, client.root);
+    const replacement = this.createClient(client.name, serverConfig, client.root, key);
     this.clients.set(key, replacement);
     rememberKnownRoot(this.knownRoots, client.name, client.root);
 
     try {
-      await replacement.start();
-      for (const filePath of openFiles) {
-        if (!fs.existsSync(filePath)) continue;
+      await withTimeout(
+        replacement.start(),
+        RECOVERY_CLIENT_STARTUP_BOUND_MS,
+        "replacement client startup bound exceeded",
+      );
+      const failedFiles: string[] = [];
+      for (const filePath of files) {
+        if (!fs.existsSync(filePath)) {
+          failedFiles.push(filePath);
+          continue;
+        }
         try {
           replacement.didOpen(filePath, fs.readFileSync(filePath, "utf-8"));
         } catch {
-          // Skip unreadable files on restart.
+          failedFiles.push(filePath);
         }
       }
-      return true;
+      for (const filePath of failedFiles) replacement.markFailedFile(filePath);
+      return { files, restarted: true };
     } catch {
       this.clients.delete(key);
       this.unavailable.set(key, "start-failed");
-      return false;
+      // A bound-exceeded start may have spawned a live process; terminate
+      // the tree so the orphan cannot outlive the failed restart.
+      void replacement.forceKill().catch(() => {});
+      return { files, restarted: false };
     }
   }
 
@@ -347,41 +518,68 @@ export class LspManager {
   }
 
   /** Wait until the client that owns a file is query-ready, then run a light warm-up probe. */
-  async waitUntilFileReady(filePath: string): Promise<LspClient | null> {
+  async waitUntilFileReady(
+    filePath: string,
+    control?: CodeRequestControl,
+  ): Promise<LspClient | null> {
+    throwIfCodeRequestInterrupted(control);
     const resolvedPath = resolveSessionPath(this.cwd, filePath);
     const client = await this.getClientForFile(resolvedPath);
     if (!client) return null;
-    await client.getReady();
-    await this.warmSemanticProject(client, resolvedPath, true);
+    // The caller's wait stops on cancellation even though the shared
+    // readiness state keeps its own lifecycle.
+    await client.getReady(control);
+    await this.warmSemanticProject(client, resolvedPath, true, control);
+    throwIfCodeRequestInterrupted(control);
     return client;
   }
 
   /**
-   * Wait until all started clients are query-ready, then warm one project file per client/root.
-   * Returns the number of concrete clients that reached readiness.
+   * Wait until one started client is query-ready, then warm its project.
+   * Returns the number of concrete clients that are ready after the warm-up.
    */
-  async waitUntilWorkspaceReady(): Promise<number> {
+  async waitUntilWorkspaceReady(control?: CodeRequestControl): Promise<number> {
+    throwIfCodeRequestInterrupted(control);
     const activeClients = Array.from(this.clients.values()).filter(
       (client) => client.status === "running",
     );
-    await Promise.all(activeClients.map((client) => client.getReady()));
+    if (activeClients.length === 0) return 0;
 
-    for (const client of activeClients) {
-      const serverConfig = this.config.servers[client.name];
-      if (!serverConfig) continue;
+    const alreadyReady = activeClients.find((client) => client.ready);
+    const firstReady =
+      alreadyReady ??
+      (await Promise.any(
+        activeClients.map(async (client) => {
+          await client.getReady(control);
+          if (client.status !== "running" || !client.ready) {
+            throw new Error("LSP client did not reach concrete readiness.");
+          }
+          return client;
+        }),
+      ).catch(() => null));
+    // Promise.any swallows individual rejections, so an interruption that
+    // raced the readiness wait must be re-raised before it degrades into a
+    // zero-ready outcome.
+    throwIfCodeRequestInterrupted(control);
+    if (!firstReady) return 0;
+
+    const serverConfig = this.config.servers[firstReady.name];
+    if (serverConfig) {
       const target = findWorkspaceSymbolWarmTargets(
-        client.root,
+        firstReady.root,
         serverConfig.rootMarkers,
         serverConfig.fileTypes,
       )[0];
-      if (!target) continue;
-      await this.warmSemanticProject(client, target.file);
+      if (target) await this.warmSemanticProject(firstReady, target.file, false, control);
     }
-    return activeClients.length;
+
+    throwIfCodeRequestInterrupted(control);
+    return activeClients.filter((client) => client.status === "running" && client.ready).length;
   }
   async syncFileAndGetDiagnostics(
     filePath: string,
     maxSeverity: number = 1,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Diagnostic[]>> {
     const resolvedPath = resolveSessionPath(this.cwd, filePath);
     const client = await this.getClientForFile(resolvedPath);
@@ -389,11 +587,11 @@ export class LspManager {
       return unavailableCodeQuery(`No LSP client can collect diagnostics for ${resolvedPath}.`);
     }
     try {
-      return {
-        kind: "completed",
-        data: await syncClientFileAndGetDiagnostics(client, resolvedPath, maxSeverity),
-      };
+      return await syncClientFileAndGetDiagnostics(client, resolvedPath, maxSeverity, control);
     } catch (error) {
+      // Cancellation must propagate; a cancelled caller no longer awaits a
+      // diagnostic result or the file cleanup side effects.
+      if (isCodeRequestInterruption(error, control)) throw error;
       this.closeFile(resolvedPath);
       const detail = error instanceof Error ? error.message : String(error);
       return unavailableCodeQuery(`Diagnostic collection failed for ${resolvedPath}: ${detail}`);
@@ -407,9 +605,12 @@ export class LspManager {
   pruneMissingFiles(): string[] {
     return pruneMissingFilesFromClients(this.clients.values());
   }
-  /** Re-sync all open documents across active clients and wait for diagnostics to settle. */
-  async refreshOpenDiagnostics(options?: { maxWaitMs?: number; quietMs?: number }): Promise<void> {
-    await refreshOpenDiagnosticsForClients(this.clients.values(), options);
+  /** Re-sync all open documents across active clients and return exact evidence coverage. */
+  async refreshOpenDiagnostics(
+    options?: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl,
+  ): Promise<DiagnosticEvidenceSummary> {
+    const summary = await refreshOpenDiagnosticsForClients(this.clients.values(), options);
+    return this.toWorkspaceDiagnosticEvidence(summary.documents);
   }
 
   /** Clear cached pull-diagnostic result IDs across all clients. */
@@ -426,21 +627,59 @@ export class LspManager {
     }
   }
 
+  /**
+   * Record one workspace invalidation event and forward it to clients.
+   *
+   * Every call with a non-empty change batch advances the invalidation
+   * generation, so a repeated edit to the same file opens a fresh
+   * generation. Recovery passes forward changes through
+   * {@link notifyWorkspaceFileChanges} and never advance the generation.
+   */
+  noteWorkspaceChanges(changes: FileEvent[]): void {
+    if (changes.length > 0) this.invalidationEpoch++;
+    this.notifyWorkspaceFileChanges(changes);
+  }
+
+  /** Return per-route diagnostic evidence capability for recovery targeting. */
+  getClientDiagnosticRoutes(): Array<{
+    key: string;
+    supportsPull: boolean;
+    unconfirmedFiles: string[];
+    stallSignal: ReturnType<LspClient["getRecoveryStallSignal"]>;
+  }> {
+    const routes: Array<{
+      key: string;
+      supportsPull: boolean;
+      unconfirmedFiles: string[];
+      stallSignal: ReturnType<LspClient["getRecoveryStallSignal"]>;
+    }> = [];
+    for (const [key, client] of this.clients) {
+      if (client.status !== "running") continue;
+      const unconfirmedFiles = client
+        .getDiagnosticSnapshot()
+        .documents.filter((document) => document.status === "unconfirmed")
+        .map((document) => uriToFile(document.uri))
+        .filter((file) => this.isDiagnosticFile(file));
+      routes.push({
+        key,
+        supportsPull: client.hasDiagnosticProvider,
+        unconfirmedFiles,
+        stallSignal: client.getRecoveryStallSignal(),
+      });
+    }
+    return routes;
+  }
+
   /** Force a workspace-wide diagnostic recovery pass. */
   async recoverWorkspaceDiagnostics(options?: {
     changes?: FileEvent[];
     restartIfStillStale?: boolean;
     maxWaitMs?: number;
     quietMs?: number;
-  }): Promise<{
-    attemptedClients: number;
-    restartedClients: number;
-    staleAssessment: {
-      suspected: boolean;
-      matchedFiles: Array<{ file: string; diagnostics: Diagnostic[] }>;
-      warning: string | null;
-    };
-  }> {
+    /** Evidence from a refresh the caller already completed; skips this pass's own refresh when no watched-file changes apply. */
+    initialEvidence?: DiagnosticEvidenceSummary;
+    control?: CodeRequestControl;
+  }): Promise<WorkspaceRecoveryResult> {
     return recoverWorkspaceDiagnosticsImpl(this, options);
   }
 
@@ -448,7 +687,12 @@ export class LspManager {
   async shutdownAll(): Promise<void> {
     const shutdowns = Array.from(this.clients.values()).map((c) => c.shutdown().catch(() => {}));
     await Promise.all(shutdowns);
+    // Dispose every client so pending or active progress tokens and
+    // readiness promises cannot outlive the manager.
+    for (const client of this.clients.values()) client.dispose();
     this.clients.clear();
+    this.clientGenerations.clear();
+    this.recoveryRestartEpochs.clear();
     this.unavailable.clear();
     this.knownRoots.clear();
     this.warmedWorkspaceSymbolProjects.clear();
@@ -456,6 +700,30 @@ export class LspManager {
     this.pendingWarmProbes.clear();
   }
   /** Get status of all servers. */
+  getRunningClientCount(): number {
+    return Array.from(this.clients.values()).filter((client) => client.status === "running").length;
+  }
+
+  /** Get the server names of all running clients, for recovery telemetry. */
+  getRunningClientNames(): string[] {
+    return Array.from(this.clients.values())
+      .filter((client) => client.status === "running")
+      .map((client) => client.name);
+  }
+
+  /** Check whether a path belongs to the configured diagnostic evidence scope. */
+  isDiagnosticFile(filePath: string): boolean {
+    const relative = path.relative(this.cwd, path.resolve(this.cwd, filePath));
+    return (
+      !shouldIgnoreLspPath(relative, this.cwd) &&
+      !isExcludedByPattern(relative, this.excludePatterns)
+    );
+  }
+
+  getDiagnosticEvidence(): DiagnosticEvidenceSummary {
+    return this.getDiagnosticSnapshot().evidence;
+  }
+
   getStatus(): ManagerStatus {
     this.pruneMissingFiles();
     const servers: ServerStatus[] = [];
@@ -538,41 +806,117 @@ export class LspManager {
       .filter((entry) => entry.openFiles.length > 0);
     return formatCoverageSummaryText(relevantEntries, maxServers, maxFiles);
   }
+  /**
+   * Capture one coherent diagnostic report from the current client snapshots.
+   *
+   * Summary and detailed projections share the same cache observation so a
+   * caller cannot combine entries from one generation with evidence from
+   * another.
+   */
+  getWorkspaceDiagnosticReport(maxSeverity: number = 2): WorkspaceDiagnosticReport {
+    this.pruneMissingFiles();
+    const snapshots = Array.from(this.clients.values()).map((client) =>
+      client.getDiagnosticSnapshot(),
+    );
+    const evidence = this.toWorkspaceDiagnosticEvidence(
+      snapshots.flatMap((snapshot) =>
+        snapshot.documents.map((document) => ({
+          file: relativeFilePathFromUri(document.uri, this.cwd),
+          status: document.status,
+        })),
+      ),
+    );
+    const current =
+      snapshots.every((snapshot) => snapshot.current) &&
+      evidence.documents.every((document) => document.status === "confirmed");
+    const fileDiags = new Map<string, { errors: number; warnings: number }>();
+    for (const snapshot of snapshots) {
+      for (const entry of snapshot.entries) {
+        collectDiagnosticSummaryCounts(fileDiags, entry, this.cwd, this.excludePatterns);
+      }
+    }
+
+    return {
+      summary: {
+        entries: Array.from(fileDiags.entries()).map(([file, counts]) => ({ file, ...counts })),
+        current,
+        evidence,
+      },
+      outstanding: {
+        entries: collectOutstandingDiagnosticsDetailed(
+          snapshots.map((snapshot) => snapshot.entries),
+          this.cwd,
+          this.excludePatterns,
+          maxSeverity,
+        ),
+        current,
+        evidence,
+      },
+    };
+  }
+
   /** Get a diagnostic summary across all servers and files. */
   getDiagnosticSummary(): DiagnosticSummary[] {
+    return this.getDiagnosticSnapshot().entries;
+  }
+  getDiagnosticSnapshot(): {
+    entries: DiagnosticSummary[];
+    current: boolean;
+    evidence: DiagnosticEvidenceSummary;
+  } {
     this.pruneMissingFiles();
     const fileDiags = new Map<string, { errors: number; warnings: number }>();
+    const evidenceDocuments: DiagnosticEvidenceDocument[] = [];
+    let clientCurrent = true;
     for (const client of this.clients.values()) {
-      for (const entry of client.getAllDiagnostics()) {
+      const snapshot = client.getDiagnosticSnapshot();
+      clientCurrent &&= snapshot.current;
+      for (const document of snapshot.documents) {
+        evidenceDocuments.push({
+          file: relativeFilePathFromUri(document.uri, this.cwd),
+          status: document.status,
+        });
+      }
+      for (const entry of snapshot.entries) {
         collectDiagnosticSummaryCounts(fileDiags, entry, this.cwd, this.excludePatterns);
       }
     }
-    return Array.from(fileDiags.entries()).map(([file, counts]) => ({ file, ...counts }));
+    const evidence = this.toWorkspaceDiagnosticEvidence(evidenceDocuments);
+    return {
+      entries: Array.from(fileDiags.entries()).map(([file, counts]) => ({ file, ...counts })),
+      current:
+        clientCurrent && evidence.documents.every((document) => document.status === "confirmed"),
+      evidence,
+    };
   }
   /** Get outstanding diagnostics at or above the configured inline threshold. */
   getOutstandingDiagnosticSummary(maxSeverity: number = 1): OutstandingDiagnosticSummaryEntry[] {
+    return this.getOutstandingDiagnosticSummarySnapshot(maxSeverity).entries;
+  }
+  getOutstandingDiagnosticSummarySnapshot(maxSeverity: number = 1): {
+    entries: OutstandingDiagnosticSummaryEntry[];
+    current: boolean;
+    evidence: DiagnosticEvidenceSummary;
+  } {
     this.pruneMissingFiles();
-    const fileDiags = new Map<string, OutstandingDiagnosticSummaryEntry>();
-    for (const client of this.clients.values()) {
-      for (const entry of client.getAllDiagnostics()) {
-        const file = relativeFilePathFromUri(entry.uri, this.cwd);
-        if (shouldIgnoreLspPath(file, this.cwd)) continue;
-        if (isExcludedByPattern(file, this.excludePatterns)) continue;
-        const current = fileDiags.get(file) ?? createOutstandingDiagnosticSummary(file);
-        const next = accumulateOutstandingDiagnostics(current, entry.diagnostics, maxSeverity);
-        if (next.total > 0) {
-          fileDiags.set(file, next);
-        }
-      }
-    }
-    return Array.from(fileDiags.values()).sort(
-      (a, b) =>
-        b.errors - a.errors ||
-        b.warnings - a.warnings ||
-        b.information - a.information ||
-        b.hints - a.hints ||
-        a.file.localeCompare(b.file),
+    const snapshots = Array.from(this.clients.values()).map((client) =>
+      client.getDiagnosticSnapshot(),
     );
+    const evidence = this.toWorkspaceDiagnosticEvidence(
+      collectClientDiagnosticEvidenceDocuments(snapshots, this.cwd),
+    );
+    const clientCurrent = snapshots.every((snapshot) => snapshot.current);
+    return {
+      entries: collectOutstandingDiagnosticSummaryEntries(
+        snapshots,
+        this.cwd,
+        this.excludePatterns,
+        maxSeverity,
+      ),
+      current:
+        clientCurrent && evidence.documents.every((document) => document.status === "confirmed"),
+      evidence,
+    };
   }
   getRelevantOutstandingDiagnosticsSummaryText(
     relevantPaths: string[],
@@ -591,28 +935,104 @@ export class LspManager {
   getOutstandingDiagnostics(
     maxSeverity: number = 1,
   ): Array<{ file: string; diagnostics: Diagnostic[] }> {
+    return this.getOutstandingDiagnosticsSnapshot(maxSeverity).entries;
+  }
+  getOutstandingDiagnosticsSnapshot(maxSeverity: number = 1): {
+    entries: Array<{ file: string; diagnostics: Diagnostic[] }>;
+    current: boolean;
+    evidence: DiagnosticEvidenceSummary;
+  } {
     this.pruneMissingFiles();
-    return collectOutstandingDiagnosticsDetailed(
-      this.clients.values(),
-      this.cwd,
-      this.excludePatterns,
-      maxSeverity,
+    const snapshots = Array.from(this.clients.values()).map((client) =>
+      client.getDiagnosticSnapshot(),
+    );
+    const evidenceDocuments = snapshots.flatMap((snapshot) =>
+      snapshot.documents.map((document) => ({
+        file: relativeFilePathFromUri(document.uri, this.cwd),
+        status: document.status,
+      })),
+    );
+    const evidence = this.toWorkspaceDiagnosticEvidence(evidenceDocuments);
+    return {
+      entries: collectOutstandingDiagnosticsDetailed(
+        snapshots.map((snapshot) => snapshot.entries),
+        this.cwd,
+        this.excludePatterns,
+        maxSeverity,
+      ),
+      current:
+        snapshots.every((snapshot) => snapshot.current) &&
+        evidence.documents.every((document) => document.status === "confirmed"),
+      evidence,
+    };
+  }
+
+  /**
+   * Aggregate the tsconfig scope decision for every tracked file.
+   *
+   * The recovery telemetry surface uses this to report why tracked files are
+   * in or out of scope without re-deriving the scope logic. The returned
+   * entry list is bounded; counts are exact.
+   */
+  getScopeDecisionSummary(): ScopeDecisionSummary {
+    this.pruneMissingFiles();
+    const accumulator: ScopeDecisionAccumulator = {
+      entries: [],
+      counts: { included: 0, excluded: 0, noConfig: 0, outOfTree: 0 },
+      basisCounts: {},
+    };
+    let totalFiles = 0;
+
+    for (const client of this.clients.values()) {
+      for (const document of client.getDiagnosticSnapshot().documents) {
+        const file = relativeFilePathFromUri(document.uri, this.cwd);
+        totalFiles++;
+        accumulateScopeDecision(accumulator, file, getFileScopeDecision(file, this.cwd));
+      }
+    }
+
+    return {
+      caseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+      counts: accumulator.counts,
+      basisCounts: accumulator.basisCounts,
+      entries: accumulator.entries,
+      totalFiles,
+    };
+  }
+  private toWorkspaceDiagnosticEvidence(
+    documents: readonly DiagnosticEvidenceDocument[],
+  ): DiagnosticEvidenceSummary {
+    const byFile = new Map<string, DiagnosticEvidenceDocument>();
+    for (const document of documents) {
+      const file = path.relative(this.cwd, path.resolve(this.cwd, document.file));
+      if (shouldIgnoreLspPath(file, this.cwd)) continue;
+      if (isExcludedByPattern(file, this.excludePatterns)) continue;
+      const existing = byFile.get(file);
+      if (!existing || evidenceStatusRank(document.status) > evidenceStatusRank(existing.status)) {
+        byFile.set(file, { file, status: document.status });
+      }
+    }
+    return summarizeDiagnosticEvidence(
+      Array.from(byFile.values()).sort((a, b) => a.file.localeCompare(b.file)),
     );
   }
+
   async workspaceSymbol(
     query: string,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<(SymbolInformation | WorkspaceSymbol)[]>> {
-    const initial = await collectWorkspaceSymbols(this.clients.values(), query);
+    const initial = await collectWorkspaceSymbols(this.clients.values(), query, control);
     if (!initial.hasSupport || initial.results.length > 0) {
       return workspaceSymbolCollectionResult(initial);
     }
 
-    const warmed = await this.warmWorkspaceSymbolProjectsUntilResult(
-      findWorkspaceSymbolWarmTargets,
-      getWorkspaceSymbolWarmPosition,
-      collectWorkspaceSymbols,
+    const warmed = await this.warmWorkspaceSymbolProjectsUntilResult({
+      findWarmTargets: findWorkspaceSymbolWarmTargets,
+      getWarmPosition: getWorkspaceSymbolWarmPosition,
+      collect: (clients, value) => collectWorkspaceSymbols(clients, value, control),
       query,
-    );
+      control,
+    });
     return workspaceSymbolCollectionResult(warmed.collection ?? initial);
   }
   async ensureFileOpen(filePath: string): Promise<LspClient | null> {
@@ -629,18 +1049,20 @@ export class LspManager {
   }
 
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: warm-up coordinates client/project iteration, targeted semantic nudges, and early-return queries in one place.
-  private async warmWorkspaceSymbolProjectsUntilResult(
+  private async warmWorkspaceSymbolProjectsUntilResult(options: {
     findWarmTargets: (
       root: string,
       rootMarkers: string[],
       fileTypes: string[],
-    ) => Array<{ projectRoot: string; file: string }>,
+    ) => Array<{ projectRoot: string; file: string }>;
     getWarmPosition: (
       symbols: import("../config/types.ts").DocumentSymbol[] | SymbolInformation[] | null,
-    ) => import("../config/types.ts").Position | null,
-    collect: (clients: Iterable<LspClient>, query: string) => Promise<WorkspaceSymbolCollection>,
-    query: string,
-  ): Promise<{ warmedAny: boolean; collection: WorkspaceSymbolCollection | null }> {
+    ) => import("../config/types.ts").Position | null;
+    collect: (clients: Iterable<LspClient>, query: string) => Promise<WorkspaceSymbolCollection>;
+    query: string;
+    control?: CodeRequestControl;
+  }): Promise<{ warmedAny: boolean; collection: WorkspaceSymbolCollection | null }> {
+    const { findWarmTargets, getWarmPosition, collect, query, control } = options;
     let warmedAny = false;
 
     for (const client of Array.from(this.clients.values())) {
@@ -667,13 +1089,20 @@ export class LspManager {
         const openedClient = await this.ensureFileOpen(target.file);
         if (!openedClient) continue;
 
+        // A cancelled pass must not mark projects warmed on its way out.
+        throwIfCodeRequestInterrupted(control);
         this.warmedWorkspaceSymbolProjects.add(projectKey);
         warmedAny = true;
 
-        const symbols = await openedClient.documentSymbols(target.file);
+        const symbols = control
+          ? await openedClient.documentSymbols(target.file, control)
+          : await openedClient.documentSymbols(target.file);
         if (symbols.kind !== "unavailable") {
           const hoverPosition = getWarmPosition(symbols.data);
-          if (hoverPosition) await openedClient.hover(target.file, hoverPosition);
+          if (hoverPosition) {
+            if (control) await openedClient.hover(target.file, hoverPosition, control);
+            else await openedClient.hover(target.file, hoverPosition);
+          }
         }
 
         const collected = await collect(this.clients.values(), query);
@@ -690,6 +1119,7 @@ export class LspManager {
     client: LspClient,
     filePath: string,
     preferExactFile: boolean = false,
+    control?: CodeRequestControl,
   ): Promise<void> {
     const serverConfig = this.config.servers[client.name];
     if (!serverConfig) return;
@@ -706,14 +1136,16 @@ export class LspManager {
 
     const pending = this.pendingWarmProbes.get(projectKey);
     if (pending) {
-      await pending;
+      // The shared probe keeps running for other consumers; only this
+      // caller's wait stops when it cancels.
+      await raceRequestControl(pending, control);
       return;
     }
 
-    const probe = this.performWarmProbe(client, resolvedFile, projectKey);
+    const probe = this.performWarmProbe(client, resolvedFile, projectKey, control);
     this.pendingWarmProbes.set(projectKey, probe);
     try {
-      await probe;
+      await raceRequestControl(probe, control);
     } finally {
       this.pendingWarmProbes.delete(projectKey);
     }
@@ -723,16 +1155,23 @@ export class LspManager {
     _client: LspClient,
     resolvedFile: string,
     projectKey: string,
+    control?: CodeRequestControl,
   ): Promise<void> {
     const openedClient = await this.ensureFileOpen(resolvedFile);
     if (!openedClient) return;
 
     this.warmedSemanticProjects.add(projectKey);
 
-    const symbols = await openedClient.documentSymbols(resolvedFile);
+    // The probe is shared state for concurrent callers. One caller's
+    // cancellation must not cancel the shared in-flight queries, so only the
+    // Debug Operation ID is forwarded; each caller races its own wait above.
+    const sharedControl = { operationId: control?.operationId };
+    const symbols = await openedClient.documentSymbols(resolvedFile, sharedControl);
     if (symbols.kind === "unavailable") return;
     const hoverPosition = getWorkspaceSymbolWarmPosition(symbols.data);
-    if (hoverPosition) await openedClient.hover(resolvedFile, hoverPosition);
+    if (hoverPosition) {
+      await openedClient.hover(resolvedFile, hoverPosition, sharedControl);
+    }
   }
 
   private hasOpenFileInProject(client: LspClient, projectRoot: string): boolean {
@@ -770,3 +1209,54 @@ export class LspManager {
     }
   }
 }
+
+function collectClientDiagnosticEvidenceDocuments(
+  snapshots: Iterable<ClientDiagnosticSnapshot>,
+  cwd: string,
+): DiagnosticEvidenceDocument[] {
+  return Array.from(snapshots).flatMap((snapshot) =>
+    snapshot.documents.map((document) => ({
+      file: relativeFilePathFromUri(document.uri, cwd),
+      status: document.status,
+    })),
+  );
+}
+
+function collectOutstandingDiagnosticSummaryEntries(
+  snapshots: Iterable<ClientDiagnosticSnapshot>,
+  cwd: string,
+  excludePatterns: string[],
+  maxSeverity: number,
+): OutstandingDiagnosticSummaryEntry[] {
+  const fileDiags = new Map<string, OutstandingDiagnosticSummaryEntry>();
+  for (const snapshot of snapshots) {
+    for (const entry of snapshot.entries) {
+      const file = relativeFilePathFromUri(entry.uri, cwd);
+      if (shouldIgnoreLspPath(file, cwd) || isExcludedByPattern(file, excludePatterns)) continue;
+      const existing = fileDiags.get(file) ?? createOutstandingDiagnosticSummary(file);
+      const next = accumulateOutstandingDiagnostics(existing, entry.diagnostics, maxSeverity);
+      if (next.total > 0) fileDiags.set(file, next);
+    }
+  }
+  return Array.from(fileDiags.values()).sort(
+    (a, b) =>
+      b.errors - a.errors ||
+      b.warnings - a.warnings ||
+      b.information - a.information ||
+      b.hints - a.hints ||
+      a.file.localeCompare(b.file),
+  );
+}
+
+function evidenceStatusRank(status: DiagnosticEvidenceDocument["status"]): number {
+  switch (status) {
+    case "confirmed":
+      return 1;
+    case "unconfirmed":
+      return 2;
+    case "failed":
+      return 3;
+    case "removed":
+      return 4;
+  }
+}