@mrclrchtr/supi-code-intelligence 6.0.0 → 6.1.0

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

@@ -21,6 +21,7 @@ import type { ClientDiagnosticSnapshot } from "../client/client-document-state.t
 
 export { RECOVERY_CLIENT_STARTUP_BOUND_MS } from "../client/client.ts";
 
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
 import { getServerForFile } from "../config/config.ts";
 import { getFileScopeDecision } from "../config/tsconfig-scope.ts";
 import type {
@@ -29,10 +30,12 @@ import type {
   FileEvent,
   LspConfig,
   ProjectServerInfo,
+  ProjectServerStatusReason,
   ServerConfig,
   SymbolInformation,
   WorkspaceSymbol,
 } from "../config/types.ts";
+import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
 import {
   accumulateOutstandingDiagnostics,
   collectDiagnosticSummaryCounts,
@@ -151,6 +154,45 @@ export interface ManagerLifecycleTransition {
 
 type ManagerLifecycleListener = (transition: ManagerLifecycleTransition) => void;
 
+type FileClientRequestOptions = {
+  /** Allow this request to start the route's one process-crash recovery. */
+  recoverProcessCrash?: boolean;
+  /** Control only this caller's wait for a shared replacement. */
+  control?: CodeRequestControl;
+};
+
+interface ProcessCrashRecoveryState {
+  /** The one automatic attempt is consumed when a replacement starts. */
+  attemptConsumed: boolean;
+  /** Current user-facing reason, or undefined after successful recovery. */
+  statusReason: ProjectServerStatusReason | undefined;
+  /** The failed generation whose tracked files must be restored. */
+  failedClient: LspClient;
+  /** Files tracked by the failed route at the time of the crash. */
+  files: string[];
+  /** Shared replacement startup and document-restoration operation. */
+  pending: Promise<LspClient | null> | null;
+  /** Start time for the current replacement attempt, when one exists. */
+  attemptStartedAt?: number;
+}
+
+type ProcessCrashRecoveryOutcome = "attempt" | "success" | "failure" | "exhausted" | "cancelled";
+
+type ProcessCrashDemandResult = {
+  /** Whether at least one required crashed route supports the operation. */
+  hasSupport: boolean;
+  /** Required routes that remain unavailable after shared recovery settles. */
+  failures: string[];
+  /** In-scope tracked files from required routes that remain unavailable. */
+  failedFiles: string[];
+};
+
+type RequiredProcessCrashDemand = {
+  key: string;
+  recovery: ProcessCrashRecoveryState;
+  failedFiles: readonly string[];
+};
+
 // ── LspManager ────────────────────────────────────────────────────────
 export class LspManager {
   /** Active clients keyed by "serverName:root" */
@@ -177,6 +219,14 @@ export class LspManager {
   private warmedSemanticProjects = new Set<string>();
   /** In-flight warm-up probes keyed by project key so concurrent callers share one probe. */
   private pendingWarmProbes = new Map<string, Promise<void>>();
+  /** One process-crash recovery budget and shared replacement per route. */
+  private processCrashRecoveries = new Map<string, ProcessCrashRecoveryState>();
+  /** Client generations that completed the initialize handshake. */
+  private initializedClientGenerations = new Map<string, number>();
+  /** Client generations whose process-failure fact was already handled. */
+  private handledCrashGenerations = new Map<string, number>();
+  /** Prevent late startup and lifecycle callbacks from republishing after shutdown. */
+  private shuttingDown = false;
   constructor(
     private readonly config: LspConfig,
     private readonly cwd: string,
@@ -247,11 +297,27 @@ export class LspManager {
   }
 
   /** Get or create an LSP client for the given file. */
-  async getClientForFile(filePath: string): Promise<LspClient | null> {
+  async getClientForFile(
+    filePath: string,
+    options: FileClientRequestOptions = {},
+  ): Promise<LspClient | null> {
+    throwIfCodeRequestInterrupted(options.control);
+    if (this.shuttingDown) return null;
     const route = this.resolveFileRoute(filePath);
-    return route ? this.startServerForRoot(route.serverName, route.root) : null;
+    if (!route) return null;
+
+    const recovery = this.processCrashRecoveries.get(route.key);
+    if (recovery && (recovery.pending || recovery.statusReason)) {
+      if (!options.recoverProcessCrash) return null;
+      return this.acquireProcessCrashReplacement(recovery, route, options.control);
+    }
+    // A recovered route keeps its consumed budget but has no active reason.
+    // Passive callers can use its running client normally.
+
+    return this.startServerForRoot(route.serverName, route.root);
   }
   async startServerForRoot(serverName: string, root: string): Promise<LspClient | null> {
+    if (this.shuttingDown) return null;
     const serverConfig = this.config.servers[serverName];
     if (!serverConfig) return null;
     const key = clientKey(serverName, root);
@@ -261,6 +327,12 @@ export class LspManager {
     const existing = this.clients.get(key);
     if (existing && existing.status === "running") return existing;
 
+    // A crashed route is retained until evidence demand starts its shared
+    // replacement. Proactive starts must not consume that budget.
+    if (existing && existing.status === "error" && this.processCrashRecoveries.has(key)) {
+      return null;
+    }
+
     // If existing client errored, remove it
     if (existing && existing.status === "error") {
       this.clients.delete(key);
@@ -315,13 +387,341 @@ export class LspManager {
     client: LspClient,
     kind: LspClientLifecycleTransitionKind,
   ): void {
+    if (this.shuttingDown) return;
     if (this.clientGenerations.get(key) !== generation) return;
     if (this.clients.get(key) !== client) return;
+
+    if (kind === "startup") {
+      this.initializedClientGenerations.set(key, generation);
+    }
+    if (kind === "crash") {
+      if (this.handledCrashGenerations.get(key) === generation) return;
+      this.handledCrashGenerations.set(key, generation);
+      if (this.initializedClientGenerations.get(key) === generation) {
+        this.handleInitializedClientCrash(key, client);
+      }
+    }
+
     const aggregateKind =
       kind === "readiness" && generation > 1 && client.ready ? "recovery" : kind;
     this.publishLifecycle(aggregateKind);
   }
 
+  private handleInitializedClientCrash(key: string, client: LspClient): void {
+    const existing = this.processCrashRecoveries.get(key);
+    if (existing?.attemptConsumed) {
+      existing.failedClient = client;
+      existing.files = this.trackedFilesForClient(client);
+      this.unavailable.set(key, "runtime-error");
+      if (existing.statusReason !== "process-crash-recovery-exhausted") {
+        existing.statusReason = "process-crash-recovery-exhausted";
+        this.recordProcessCrashRecoveryEvent(
+          client.name,
+          client.root,
+          "exhausted",
+          existing.pending ? existing.attemptStartedAt : Date.now(),
+        );
+      }
+      return;
+    }
+
+    this.processCrashRecoveries.set(key, {
+      attemptConsumed: false,
+      statusReason: "process-crashed",
+      failedClient: client,
+      files: this.trackedFilesForClient(client),
+      pending: null,
+    });
+  }
+
+  private trackedFilesForClient(client: LspClient): string[] {
+    const files = new Set(client.openFiles);
+    for (const document of client.getDiagnosticSnapshot().documents) {
+      files.add(uriToFile(document.uri));
+    }
+    return Array.from(files);
+  }
+
+  private waitForProcessCrashRecovery(
+    recovery: ProcessCrashRecoveryState,
+    control?: CodeRequestControl,
+  ): Promise<LspClient | null> {
+    if (!recovery.pending) return Promise.resolve(null);
+    return raceRequestControl(recovery.pending, control);
+  }
+
+  private acquireProcessCrashReplacement(
+    recovery: ProcessCrashRecoveryState,
+    route: FileRoute,
+    control?: CodeRequestControl,
+  ): Promise<LspClient | null> {
+    if (recovery.pending) return this.waitForProcessCrashRecovery(recovery, control);
+    if (
+      recovery.statusReason === "process-crashed" &&
+      !recovery.attemptConsumed &&
+      !this.shuttingDown
+    ) {
+      return this.startProcessCrashRecovery(recovery, route, control);
+    }
+    return Promise.resolve(null);
+  }
+
+  /**
+   * Recover all crashed routes selected by one evidence-producing operation.
+   * Each route keeps its independent attempt budget and shared replacement.
+   */
+  private async recoverProcessCrashDemand(
+    selectFiles: (recovery: ProcessCrashRecoveryState) => readonly string[] | null,
+    control?: CodeRequestControl,
+  ): Promise<ProcessCrashDemandResult> {
+    const required = Array.from(this.processCrashRecoveries.entries()).flatMap(
+      ([key, recovery]): RequiredProcessCrashDemand[] => {
+        if (recovery.statusReason === undefined) return [];
+        const failedFiles = selectFiles(recovery);
+        return failedFiles === null ? [] : [{ key, recovery, failedFiles }];
+      },
+    );
+    if (required.length === 0) return { hasSupport: false, failures: [], failedFiles: [] };
+
+    await Promise.all(
+      required.map(async ({ key, recovery }) => {
+        const serverConfig = this.config.servers[recovery.failedClient.name];
+        if (!serverConfig) return;
+        await this.acquireProcessCrashReplacement(
+          recovery,
+          {
+            serverName: recovery.failedClient.name,
+            serverConfig,
+            root: recovery.failedClient.root,
+            key,
+          },
+          control,
+        );
+      }),
+    );
+
+    const failedDemands = required.filter(({ recovery }) => recovery.statusReason !== undefined);
+    return {
+      hasSupport: true,
+      failures: failedDemands.map(({ recovery }) => this.formatProcessCrashDemandFailure(recovery)),
+      failedFiles: Array.from(new Set(failedDemands.flatMap(({ failedFiles }) => failedFiles))),
+    };
+  }
+
+  private formatProcessCrashDemandFailure(recovery: ProcessCrashRecoveryState): string {
+    const root = (path.relative(this.cwd, recovery.failedClient.root) || ".").replaceAll("\\", "/");
+    const reason =
+      recovery.statusReason === "process-crash-recovery-exhausted"
+        ? "process recovery exhausted; reload required"
+        : recovery.statusReason === "process-crash-recovery-pending"
+          ? "process recovery in progress"
+          : "process crashed";
+    return `${recovery.failedClient.name} @ ${root} is unavailable — ${reason}.`;
+  }
+
+  private startProcessCrashRecovery(
+    recovery: ProcessCrashRecoveryState,
+    route: FileRoute,
+    control?: CodeRequestControl,
+  ): Promise<LspClient | null> {
+    throwIfCodeRequestInterrupted(control);
+    recovery.attemptConsumed = true;
+    recovery.statusReason = "process-crash-recovery-pending";
+    recovery.attemptStartedAt = Date.now();
+    const pending = this.performProcessCrashRecovery(recovery, route);
+    recovery.pending = pending;
+    // A cancelled caller may be the only current waiter. Keep the shared
+    // replacement promise observed until it settles without adopting that
+    // caller's cancellation or deadline.
+    pending.catch(() => {});
+    this.recordProcessCrashRecoveryEvent(
+      route.serverName,
+      route.root,
+      "attempt",
+      recovery.attemptStartedAt,
+    );
+    this.publishLifecycle("recovery");
+    return raceRequestControl(pending, control);
+  }
+
+  private async performProcessCrashRecovery(
+    recovery: ProcessCrashRecoveryState,
+    route: FileRoute,
+  ): Promise<LspClient | null> {
+    const key = route.key;
+    const attemptStartedAt = recovery.attemptStartedAt;
+
+    try {
+      // A process-error event can leave the child alive. Stop the old tree
+      // before installing its replacement, but retain its captured evidence.
+      await recovery.failedClient.forceKill().catch(() => {});
+      if (this.isProcessCrashRecoveryCancelled(recovery, key)) {
+        this.recordProcessCrashRecoveryEvent(
+          route.serverName,
+          route.root,
+          "cancelled",
+          attemptStartedAt,
+        );
+        return null;
+      }
+
+      const replacement = this.installProcessCrashReplacement(recovery, route);
+      const started = await this.startProcessCrashReplacement(recovery, route, replacement);
+      if (!started) return null;
+
+      // A replacement can crash after initialize and before this operation
+      // resumes. Its lifecycle callback has already exhausted the route.
+      if (
+        started.status !== "running" ||
+        recovery.statusReason === "process-crash-recovery-exhausted"
+      ) {
+        return null;
+      }
+
+      this.unavailable.delete(key);
+      recovery.statusReason = undefined;
+      this.publishLifecycle("recovery");
+      this.restoreTrackedDocuments(started, recovery.files);
+      this.recordProcessCrashRecoveryEvent(
+        route.serverName,
+        route.root,
+        "success",
+        attemptStartedAt,
+      );
+      return started;
+    } finally {
+      if (this.processCrashRecoveries.get(key) === recovery) recovery.pending = null;
+    }
+  }
+
+  private isProcessCrashRecoveryCancelled(
+    recovery: ProcessCrashRecoveryState,
+    key: string,
+  ): boolean {
+    return this.shuttingDown || this.processCrashRecoveries.get(key) !== recovery;
+  }
+
+  private installProcessCrashReplacement(
+    recovery: ProcessCrashRecoveryState,
+    route: FileRoute,
+  ): LspClient {
+    const key = route.key;
+    if (this.clients.get(key) === recovery.failedClient) this.clients.delete(key);
+    this.clearWarmedWorkspaceSymbolProjects(route.serverName, route.root);
+    this.clearWarmedSemanticProjects(route.serverName, route.root);
+    this.clearPendingWarmProbes(route.serverName, route.root);
+
+    const replacement = this.createClient(route.serverName, route.serverConfig, route.root, key);
+    this.clients.set(key, replacement);
+    rememberKnownRoot(this.knownRoots, route.serverName, route.root);
+    return replacement;
+  }
+
+  private async startProcessCrashReplacement(
+    recovery: ProcessCrashRecoveryState,
+    route: FileRoute,
+    replacement: LspClient,
+  ): Promise<LspClient | null> {
+    try {
+      // LspClient's initialize request already has the 30-second transport
+      // bound. Do not apply the 5-second diagnostic-restart bound here.
+      await replacement.start();
+    } catch {
+      if (this.isProcessCrashRecoveryCancelled(recovery, route.key)) {
+        await replacement.forceKill().catch(() => {});
+        this.recordProcessCrashRecoveryEvent(
+          route.serverName,
+          route.root,
+          "cancelled",
+          recovery.attemptStartedAt,
+        );
+        return null;
+      }
+      if (recovery.statusReason !== "process-crash-recovery-exhausted") {
+        this.markProcessCrashRecoveryFailed(recovery, route.key, replacement);
+        this.recordProcessCrashRecoveryEvent(
+          route.serverName,
+          route.root,
+          "failure",
+          recovery.attemptStartedAt,
+        );
+      }
+      return null;
+    }
+
+    if (
+      this.isProcessCrashRecoveryCancelled(recovery, route.key) ||
+      this.clients.get(route.key) !== replacement
+    ) {
+      await replacement.forceKill().catch(() => {});
+      this.recordProcessCrashRecoveryEvent(
+        route.serverName,
+        route.root,
+        "cancelled",
+        recovery.attemptStartedAt,
+      );
+      return null;
+    }
+    return replacement;
+  }
+
+  /** Restore route documents from disk and retain failed-document evidence. */
+  private restoreTrackedDocuments(client: LspClient, files: readonly string[]): void {
+    const failedFiles: string[] = [];
+    for (const filePath of files) {
+      if (!fs.existsSync(filePath)) {
+        failedFiles.push(filePath);
+        continue;
+      }
+      try {
+        client.didOpen(filePath, fs.readFileSync(filePath, "utf-8"));
+      } catch {
+        failedFiles.push(filePath);
+      }
+    }
+    for (const filePath of failedFiles) client.markFailedFile(filePath);
+  }
+
+  private markProcessCrashRecoveryFailed(
+    recovery: ProcessCrashRecoveryState,
+    key: string,
+    replacement: LspClient,
+  ): void {
+    recovery.statusReason = "process-crash-recovery-exhausted";
+    this.unavailable.set(key, "start-failed");
+    if (this.clients.get(key) === replacement) this.clients.delete(key);
+    // A failed initialize may still leave a child process alive. The
+    // replacement is no longer owned by the manager before it is terminated.
+    void replacement.forceKill().catch(() => {});
+    this.publishLifecycle("recovery");
+  }
+
+  private recordProcessCrashRecoveryEvent(
+    serverName: string,
+    root: string,
+    outcome: ProcessCrashRecoveryOutcome,
+    startedAt?: number,
+  ): void {
+    try {
+      recordDebugEvent({
+        source: "lsp",
+        level: outcome === "failure" || outcome === "exhausted" ? "warning" : "debug",
+        category: "runtime.recovery",
+        message: `LSP process-crash recovery ${outcome}`,
+        cwd: boundCwd(this.cwd),
+        data: {
+          reason: "process-crash",
+          outcome,
+          server: truncateIdentity(serverName),
+          root: truncateIdentity(root),
+          elapsedMs: startedAt === undefined ? 0 : Math.max(0, Date.now() - startedAt),
+        },
+      });
+    } catch {
+      // Recovery telemetry must never change route behavior.
+    }
+  }
+
   private publishLifecycle(kind: ManagerLifecycleTransitionKind): void {
     if (!this.onLifecycleTransition) return;
     const projectServers = this.getKnownProjectServers([]);
@@ -360,11 +760,16 @@ export class LspManager {
     rememberKnownRoot(this.knownRoots, serverName, root);
     try {
       await client.start();
+      if (this.shuttingDown) {
+        await client.forceKill().catch(() => {});
+        if (this.clients.get(key) === client) this.clients.delete(key);
+        return null;
+      }
       this.unavailable.delete(key);
       return client;
     } catch {
       this.unavailable.set(key, "start-failed");
-      this.clients.delete(key);
+      if (this.clients.get(key) === client) this.clients.delete(key);
       return null;
     }
   }
@@ -408,6 +813,8 @@ export class LspManager {
       if (options?.pushOnly && client.hasDiagnosticProvider) continue;
 
       const key = clientKey(client.name, client.root);
+      const processRecovery = this.processCrashRecoveries.get(key);
+      if (processRecovery?.pending) continue;
       if (seen.has(key)) continue;
       seen.add(key);
       if (this.recoveryRestartEpochs.get(key) === this.invalidationEpoch) continue;
@@ -455,19 +862,8 @@ export class LspManager {
         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 {
-          failedFiles.push(filePath);
-        }
-      }
-      for (const filePath of failedFiles) replacement.markFailedFile(filePath);
+      this.restoreTrackedDocuments(replacement, files);
+      this.clearUnconsumedProcessCrashState(key, client);
       return { files, restarted: true };
     } catch {
       this.clients.delete(key);
@@ -479,6 +875,13 @@ export class LspManager {
     }
   }
 
+  private clearUnconsumedProcessCrashState(key: string, failedClient: LspClient): void {
+    const recovery = this.processCrashRecoveries.get(key);
+    if (recovery?.failedClient !== failedClient || recovery.attemptConsumed) return;
+    this.processCrashRecoveries.delete(key);
+    this.publishLifecycle("recovery");
+  }
+
   getProjectServerInfo(serverName: string, root: string, fileTypes: string[]): ProjectServerInfo {
     const key = clientKey(serverName, root);
     return buildProjectServerInfo(
@@ -489,6 +892,7 @@ export class LspManager {
         client: this.clients.get(key),
         unavailableReason:
           this.getUnavailableReason(key, this.config.servers[serverName]?.command) ?? undefined,
+        statusReason: this.processCrashRecoveries.get(key)?.statusReason,
       },
       this.cwd,
     );
@@ -507,6 +911,19 @@ export class LspManager {
         fileTypes: [...(this.config.servers[client.name]?.fileTypes ?? [])],
       });
     }
+    // Keep an exhausted recovery route visible after its failed replacement
+    // is removed from the active client pool.
+    for (const recovery of this.processCrashRecoveries.values()) {
+      const name = recovery.failedClient.name;
+      const root = recovery.failedClient.root;
+      const key = clientKey(name, root);
+      if (known.has(key)) continue;
+      known.set(key, {
+        name,
+        root,
+        fileTypes: [...(this.config.servers[name]?.fileTypes ?? [])],
+      });
+    }
     return Array.from(known.values())
       .map((entry) => this.getProjectServerInfo(entry.name, entry.root, entry.fileTypes))
       .sort(
@@ -524,7 +941,10 @@ export class LspManager {
   ): Promise<LspClient | null> {
     throwIfCodeRequestInterrupted(control);
     const resolvedPath = resolveSessionPath(this.cwd, filePath);
-    const client = await this.getClientForFile(resolvedPath);
+    const client = await this.getClientForFile(resolvedPath, {
+      recoverProcessCrash: true,
+      control,
+    });
     if (!client) return null;
     // The caller's wait stops on cancellation even though the shared
     // readiness state keeps its own lifecycle.
@@ -582,7 +1002,10 @@ export class LspManager {
     control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Diagnostic[]>> {
     const resolvedPath = resolveSessionPath(this.cwd, filePath);
-    const client = await this.getClientForFile(resolvedPath);
+    const client = await this.getClientForFile(resolvedPath, {
+      recoverProcessCrash: true,
+      control,
+    });
     if (!client) {
       return unavailableCodeQuery(`No LSP client can collect diagnostics for ${resolvedPath}.`);
     }
@@ -678,20 +1101,83 @@ export class LspManager {
     quietMs?: number;
     /** Evidence from a refresh the caller already completed; skips this pass's own refresh when no watched-file changes apply. */
     initialEvidence?: DiagnosticEvidenceSummary;
+    /** Explicit demand to recover crashed routes with tracked files in scope. */
+    processCrashDemand?: { scopes?: readonly string[] };
     control?: CodeRequestControl;
   }): Promise<WorkspaceRecoveryResult> {
-    return recoverWorkspaceDiagnosticsImpl(this, options);
+    const demand = options?.processCrashDemand
+      ? await this.recoverProcessCrashDemand((recovery) => {
+          const files = this.processCrashDiagnosticFiles(recovery, options.processCrashDemand);
+          return files.length > 0 ? files : null;
+        }, options.control)
+      : { hasSupport: false, failures: [], failedFiles: [] };
+    const recoveryOptions = demand.hasSupport
+      ? { ...options, initialEvidence: undefined }
+      : options;
+    const result = await recoverWorkspaceDiagnosticsImpl(this, recoveryOptions);
+    return this.addProcessCrashDiagnosticEvidence(result, demand);
+  }
+
+  private processCrashDiagnosticFiles(
+    recovery: ProcessCrashRecoveryState,
+    demand: { scopes?: readonly string[] } | undefined,
+  ): string[] {
+    if (!demand) return [];
+    const scopes = demand.scopes?.map((scope) => resolveSessionPath(this.cwd, scope));
+    return recovery.files.filter(
+      (file) =>
+        this.isDiagnosticFile(file) &&
+        (!scopes ||
+          scopes.length === 0 ||
+          scopes.some((scope) => projectRoots.isWithinOrEqual(scope, file))),
+    );
+  }
+
+  private addProcessCrashDiagnosticEvidence(
+    result: WorkspaceRecoveryResult,
+    demand: ProcessCrashDemandResult,
+  ): WorkspaceRecoveryResult {
+    if (demand.failures.length === 0) return result;
+    const byFile = new Map(
+      result.diagnosticEvidence.documents.map((document) => [document.file, document] as const),
+    );
+    for (const file of demand.failedFiles) {
+      const relativeFile = path.relative(this.cwd, file);
+      byFile.set(relativeFile, { file: relativeFile, status: "failed" });
+    }
+    const diagnosticEvidence = summarizeDiagnosticEvidence(Array.from(byFile.values()));
+    const diagnosticReport = {
+      summary: { ...result.diagnosticReport.summary, current: false, evidence: diagnosticEvidence },
+      outstanding: {
+        ...result.diagnosticReport.outstanding,
+        current: false,
+        evidence: diagnosticEvidence,
+      },
+    };
+    return {
+      ...result,
+      diagnosticEvidence,
+      diagnosticReport,
+      refreshFailureReason: [result.refreshFailureReason, ...demand.failures]
+        .filter(Boolean)
+        .join("; "),
+    };
   }
 
   /** Shut down all running LSP servers. */
   async shutdownAll(): Promise<void> {
-    const shutdowns = Array.from(this.clients.values()).map((c) => c.shutdown().catch(() => {}));
+    this.shuttingDown = true;
+    const clients = Array.from(this.clients.values());
+    const shutdowns = clients.map((client) => client.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();
+    for (const client of clients) client.dispose();
     this.clients.clear();
     this.clientGenerations.clear();
+    this.initializedClientGenerations.clear();
+    this.handledCrashGenerations.clear();
+    this.processCrashRecoveries.clear();
     this.recoveryRestartEpochs.clear();
     this.unavailable.clear();
     this.knownRoots.clear();
@@ -1020,8 +1506,34 @@ export class LspManager {
   async workspaceSymbol(
     query: string,
     control?: CodeRequestControl,
+    scopes?: readonly string[],
   ): Promise<CodeQueryResult<(SymbolInformation | WorkspaceSymbol)[]>> {
-    const initial = await collectWorkspaceSymbols(this.clients.values(), query, control);
+    const resolvedScopes = scopes?.map((scope) => resolveSessionPath(this.cwd, scope));
+    const routeMatches = (client: LspClient) =>
+      this.workspaceSymbolRouteMatchesScopes(client, resolvedScopes);
+    if (resolvedScopes && !this.hasWorkspaceSymbolRouteForScopes(resolvedScopes)) {
+      return unavailableCodeQuery(
+        "No known LSP route intersects the requested workspace-symbol scope.",
+      );
+    }
+    const demand = await this.recoverProcessCrashDemand(
+      (recovery) =>
+        recovery.failedClient.serverCapabilities?.workspaceSymbolProvider &&
+        routeMatches(recovery.failedClient)
+          ? []
+          : null,
+      control,
+    );
+    const collect = async (clients: Iterable<LspClient>, value: string) =>
+      this.addWorkspaceSymbolDemandEvidence(
+        await collectWorkspaceSymbols(
+          Array.from(clients).filter((client) => routeMatches(client)),
+          value,
+          control,
+        ),
+        demand,
+      );
+    const initial = await collect(this.clients.values(), query);
     if (!initial.hasSupport || initial.results.length > 0) {
       return workspaceSymbolCollectionResult(initial);
     }
@@ -1029,15 +1541,57 @@ export class LspManager {
     const warmed = await this.warmWorkspaceSymbolProjectsUntilResult({
       findWarmTargets: findWorkspaceSymbolWarmTargets,
       getWarmPosition: getWorkspaceSymbolWarmPosition,
-      collect: (clients, value) => collectWorkspaceSymbols(clients, value, control),
+      collect,
+      routeMatches,
       query,
       control,
     });
     return workspaceSymbolCollectionResult(warmed.collection ?? initial);
   }
-  async ensureFileOpen(filePath: string): Promise<LspClient | null> {
+
+  private addWorkspaceSymbolDemandEvidence(
+    collection: WorkspaceSymbolCollection,
+    demand: ProcessCrashDemandResult,
+  ): WorkspaceSymbolCollection {
+    return {
+      ...collection,
+      hasSupport: collection.hasSupport || demand.hasSupport,
+      failures: [...collection.failures, ...demand.failures],
+    };
+  }
+
+  private hasWorkspaceSymbolRouteForScopes(scopes: readonly string[]): boolean {
+    const clients = [
+      ...this.clients.values(),
+      ...Array.from(this.processCrashRecoveries.values(), (recovery) => recovery.failedClient),
+    ];
+    return clients.some((client) => this.workspaceSymbolRouteMatchesScopes(client, scopes));
+  }
+
+  private workspaceSymbolRouteMatchesScopes(
+    client: LspClient,
+    scopes: readonly string[] | undefined,
+  ): boolean {
+    if (!scopes || scopes.length === 0) return true;
+    const key = clientKey(client.name, client.root);
+    return scopes.some((scope) => {
+      try {
+        if (fs.statSync(scope).isFile()) return this.resolveFileRoute(scope)?.key === key;
+      } catch {
+        return false;
+      }
+      return (
+        projectRoots.isWithinOrEqual(client.root, scope) ||
+        projectRoots.isWithinOrEqual(scope, client.root)
+      );
+    });
+  }
+  async ensureFileOpen(
+    filePath: string,
+    options: FileClientRequestOptions = {},
+  ): Promise<LspClient | null> {
     const resolvedPath = resolveSessionPath(this.cwd, filePath);
-    const client = await this.getClientForFile(resolvedPath);
+    const client = await this.getClientForFile(resolvedPath, options);
     if (!client) return null;
     try {
       client.didOpen(resolvedPath, fs.readFileSync(resolvedPath, "utf-8"));
@@ -1059,13 +1613,15 @@ export class LspManager {
       symbols: import("../config/types.ts").DocumentSymbol[] | SymbolInformation[] | null,
     ) => import("../config/types.ts").Position | null;
     collect: (clients: Iterable<LspClient>, query: string) => Promise<WorkspaceSymbolCollection>;
+    routeMatches?: (client: LspClient) => boolean;
     query: string;
     control?: CodeRequestControl;
   }): Promise<{ warmedAny: boolean; collection: WorkspaceSymbolCollection | null }> {
-    const { findWarmTargets, getWarmPosition, collect, query, control } = options;
+    const { findWarmTargets, getWarmPosition, collect, routeMatches, query, control } = options;
     let warmedAny = false;
 
     for (const client of Array.from(this.clients.values())) {
+      if (routeMatches && !routeMatches(client)) continue;
       if (client.status !== "running") continue;
       if (!client.serverCapabilities?.workspaceSymbolProvider) continue;