@mrclrchtr/supi-lsp 11.2.0 → 11.3.0

package/src/manager/manager.ts

@@ -19,6 +19,7 @@ import {
   withTimeout,
 } from "../client/client.ts";
 import type { ClientDiagnosticSnapshot } from "../client/client-document-state.ts";
+import type { ProjectMembership } from "../client/client-typescript-project.ts";
 
 export { RECOVERY_CLIENT_STARTUP_BOUND_MS } from "../client/client.ts";
 
@@ -135,8 +136,10 @@ import {
   collectWorkspaceSymbols,
   findWorkspaceSymbolWarmTargets,
   getWorkspaceSymbolWarmPosition,
+  isWithinAnyScope,
   type WorkspaceSymbolCollection,
   workspaceSymbolCollectionResult,
+  workspaceSymbolCoverageGap,
 } from "./manager-workspace-symbol.ts";
 
 type UnavailableReason = "missing-command" | "start-failed" | "runtime-error";
@@ -251,6 +254,8 @@ export interface ManagerLifecycleTransition {
 type ManagerLifecycleListener = (transition: ManagerLifecycleTransition) => void;
 
 type FileClientRequestOptions = {
+  /** Reject known input changes while this call's first open waits to dispatch original parameters. */
+  protectInputs?: boolean;
   /** Allow this request to start the route's one process-crash recovery. */
   recoverProcessCrash?: boolean;
   /** Control only this caller's wait for a shared replacement. */
@@ -397,8 +402,12 @@ export class LspManager {
   private invalidationEpoch = 0;
   /** Invalidation generation in which each route last received a recovery restart. */
   private recoveryRestartEpochs = new Map<string, number>();
-  /** Files already probed for workspace-symbol warm-up. */
-  private warmedWorkspaceSymbolFiles = new Set<string>();
+  /**
+   * Files already probed for workspace-symbol warm-up, with the project
+   * membership the server reported. `inferred` probes stay recorded so they
+   * are not reopened, but they do not prove project coverage.
+   */
+  private warmedWorkspaceSymbolFiles = new Map<string, ProjectMembership>();
   /** Project roots whose semantic state was warmed with a readiness probe. */
   private warmedSemanticProjects = new Set<string>();
   /** In-flight warm-up probes keyed by project key so concurrent callers share one probe. */
@@ -434,6 +443,19 @@ export class LspManager {
       detected.filter((entry) => this.automaticPathPolicy.isEligible(entry.root, "directory")),
     );
   }
+  /** Check configured routing only, independently of executable availability or startup state. */
+  hasConfiguredServerForFile(filePath: string): boolean {
+    return getServerForFile(this.config, resolveSessionPath(this.cwd, filePath)) !== null;
+  }
+
+  /** Observe a retained initial-start failure without retrying or conflating process-crash recovery. */
+  hasFailedStartupForFile(filePath: string): boolean {
+    const route = this.resolveFileRoute(filePath);
+    if (!route || this.processCrashRecoveries.has(route.key)) return false;
+    const reason = this.unavailable.get(route.key);
+    return reason === "start-failed" || reason === "missing-command";
+  }
+
   /** Check whether a file path has an available LSP server for explicit semantic operations. */
   canServeFile(filePath: string): boolean {
     const route = this.resolveFileRoute(filePath);
@@ -1314,7 +1336,13 @@ export class LspManager {
       recovery.statusReason = undefined;
       recovery.failureMessage = undefined;
       this.publishLifecycle("recovery");
-      this.restoreTrackedDocuments(started, recovery.files);
+      await this.restoreTrackedDocuments(started, recovery.files);
+      if (
+        this.isProcessCrashRecoveryCancelled(recovery, key) ||
+        this.clients.get(key) !== started ||
+        started.status !== "running"
+      )
+        return null;
       this.recordProcessCrashRecoveryEvent(
         route.serverName,
         route.root,
@@ -1399,20 +1427,16 @@ export class LspManager {
   }
 
   /** Restore route documents from disk and retain failed-document evidence. */
-  private restoreTrackedDocuments(client: LspClient, files: readonly string[]): void {
-    const failedFiles: string[] = [];
+  private async restoreTrackedDocuments(
+    client: LspClient,
+    files: readonly string[],
+  ): Promise<void> {
+    const key = clientKey(client.name, client.root);
+    const isCurrent = () => !this.shuttingDown && this.clients.get(key) === client;
     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);
-      }
+      if (!isCurrent()) return;
+      await client.restoreDocument(filePath, () => fs.readFileSync(filePath, "utf-8"), isCurrent);
     }
-    for (const filePath of failedFiles) client.markFailedFile(filePath);
   }
 
   private markProcessCrashRecoveryFailed(
@@ -1656,7 +1680,15 @@ export class LspManager {
         void replacement.forceKill().catch(() => {});
         return { files, restarted: false };
       }
-      this.restoreTrackedDocuments(replacement, files);
+      await this.restoreTrackedDocuments(replacement, files);
+      if (
+        this.clients.get(key) !== replacement ||
+        this.shuttingDown ||
+        replacement.status !== "running"
+      ) {
+        void replacement.forceKill().catch(() => {});
+        return { files, restarted: false };
+      }
       this.clearUnconsumedProcessCrashState(key, client);
       return { files, restarted: true };
     } catch {
@@ -1766,7 +1798,9 @@ export class LspManager {
     if (options.retryFailedRoute) {
       this.retireMissingProjectRoots();
       const route = this.resolveFileRoute(resolvedPath);
-      if (!route || !this.automaticPathPolicy.isEligible(route.root, "directory")) {
+      // Exact-file demand, including refresh, bypasses automatic discovery exclusions.
+      // Keep the original route identity for document synchronization and bounded retries.
+      if (!route) {
         return {
           client: null,
           processCrashRecovery: emptyProcessCrashRecoveryReport(),
@@ -2050,13 +2084,19 @@ export class LspManager {
 
     const serverConfig = this.config.servers[firstReady.name];
     if (serverConfig) {
-      const target = findWorkspaceSymbolWarmTargets(
+      // Candidates for the best-ranked marker root; later ones replace a probe
+      // that lands in an inferred project outside the configured program.
+      const targets = findWorkspaceSymbolWarmTargets(
         firstReady.root,
         serverConfig.rootMarkers,
         serverConfig.fileTypes,
         { policy: this.automaticPathPolicy },
-      )[0];
-      if (target) await this.warmSemanticProject(firstReady, target.file, false, control);
+      );
+      const primaryRoot = targets[0]?.projectRoot;
+      const files = targets
+        .filter((target) => target.projectRoot === primaryRoot)
+        .map((target) => target.file);
+      if (files.length > 0) await this.warmSemanticProject(firstReady, files, false, control);
       // The warm-up request can start server indexing after the initial
       // readiness wait resolves. Observe the resulting progress before
       // reporting the workspace as ready.
@@ -2899,7 +2939,20 @@ export class LspManager {
       return this.filterWorkspaceSymbolCollection(collection, resolvedScopes);
     };
     const initial = await collect(this.clients.values(), query);
-    if (!initial.hasSupport || initial.results.length > 0) {
+    // Allowed out-of-scope rows do not show that the server knows the scope yet.
+    const hasScopedResult = (collection: WorkspaceSymbolCollection) =>
+      collection.hasSupport &&
+      collection.results.some(
+        (result) =>
+          !resolvedScopes?.length ||
+          isWithinAnyScope(uriToFile(result.location.uri), resolvedScopes),
+      );
+    // Rows from a route whose warm-up reached only inferred projects may come
+    // from those files alone, so they cannot end the search early.
+    if (
+      !initial.hasSupport ||
+      (hasScopedResult(initial) && !this.hasInferredOnlyWarmRoute(routeMatches))
+    ) {
       return workspaceSymbolCollectionResult(initial);
     }
 
@@ -2911,11 +2964,32 @@ export class LspManager {
         }),
       getWarmPosition: getWorkspaceSymbolWarmPosition,
       collect,
+      hasResult: hasScopedResult,
       routeMatches,
       query,
       control,
     });
-    return workspaceSymbolCollectionResult(warmed.collection ?? initial);
+    const collection = warmed.collection ?? initial;
+    return workspaceSymbolCollectionResult(
+      warmed.coverageConfirmed
+        ? collection
+        : workspaceSymbolCoverageGap(collection, warmed.inferredProbeCount),
+    );
+  }
+
+  /** True when a matching route has inferred warm-up probes and no other probe. */
+  private hasInferredOnlyWarmRoute(routeMatches: (client: LspClient) => boolean): boolean {
+    return Array.from(this.clients.values()).some((client) => {
+      if (!routeMatches(client)) return false;
+      const prefix = `${client.name}:${path.resolve(client.root)}`;
+      let inferred = false;
+      for (const [key, membership] of this.warmedWorkspaceSymbolFiles) {
+        if (key !== prefix && !key.startsWith(`${prefix}${path.sep}`)) continue;
+        if (membership !== "inferred") return false;
+        inferred = true;
+      }
+      return inferred;
+    });
   }
 
   private addWorkspaceSymbolDemandEvidence(
@@ -2938,6 +3012,7 @@ export class LspManager {
     const results = collection.results.filter((result) => {
       const file = uriToFile(result.location.uri);
       if (this.isWorkspaceSymbolResultAllowed(file, scopes)) return true;
+      if (!this.isWorkspaceSymbolExclusionRelevant(file, scopes)) return false;
       excludedCount++;
       const example = displayRelativeFilePath(file, this.cwd);
       if (excludedExamples.size < 5) excludedExamples.add(example);
@@ -2951,6 +3026,26 @@ export class LspManager {
     };
   }
 
+  /** Only proven-disjoint exclusions can be omitted from scoped completeness. */
+  private isWorkspaceSymbolExclusionRelevant(
+    filePath: string,
+    scopes: readonly string[] | undefined,
+  ): boolean {
+    if (!scopes?.length || !path.isAbsolute(filePath)) return true;
+    if (scopes.some((scope) => projectRoots.isWithinOrEqual(scope, filePath))) return true;
+    try {
+      // Observed spellings and physical identities both matter: an excluded
+      // alias may point into scope even when its spelling is outside it.
+      const physicalFile = fs.realpathSync(filePath);
+      return scopes.some((scope) =>
+        projectRoots.isWithinOrEqual(fs.realpathSync(scope), physicalFile),
+      );
+    } catch {
+      // Missing, unreadable or otherwise unresolved paths cannot prove absence.
+      return true;
+    }
+  }
+
   /** Keep explicitly selected excluded scopes inspectable while filtering broad results. */
   private isWorkspaceSymbolResultAllowed(
     filePath: string,
@@ -3045,15 +3140,22 @@ export class LspManager {
     const client = await this.getClientForFile(resolvedPath, options);
     if (!client) return null;
     try {
-      const content = fs.readFileSync(resolvedPath, "utf-8");
-      // Route startup can be shared. The document open belongs to this
-      // caller, so check again after the shared wait before sending didOpen.
-      throwIfCodeRequestInterrupted(options.control);
-      client.didOpen(resolvedPath, content);
+      await client.openDocument(
+        resolvedPath,
+        () => {
+          try {
+            return fs.readFileSync(resolvedPath, "utf-8");
+          } catch (error) {
+            this.closeFile(resolvedPath);
+            throw error;
+          }
+        },
+        options.control,
+        options.protectInputs,
+      );
       return client;
     } catch (error) {
       if (isCodeRequestInterruption(error, options.control)) throw error;
-      this.closeFile(resolvedPath);
       return null;
     }
   }
@@ -3069,13 +3171,29 @@ 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>;
+    /** Stop warming once a collection contains a row that answers the request. */
+    hasResult: (collection: WorkspaceSymbolCollection) => boolean;
     routeMatches?: (client: LspClient) => boolean;
     query: string;
     control?: CodeRequestControl;
-  }): Promise<{ warmedAny: boolean; collection: WorkspaceSymbolCollection | null }> {
-    const { findWarmTargets, getWarmPosition, collect, routeMatches, query, control } = options;
-    let warmedAny = false;
+  }): Promise<{
+    collection: WorkspaceSymbolCollection | null;
+    /** False only when every probe the server classified landed in an inferred project. */
+    coverageConfirmed: boolean;
+    inferredProbeCount: number;
+  }> {
+    const { findWarmTargets, getWarmPosition, collect, hasResult, routeMatches, query, control } =
+      options;
     let latestCollection: WorkspaceSymbolCollection | null = null;
+    // A route with no inferred probe keeps today's evidence: non-TypeScript
+    // servers index the workspace, and `unknown` cannot prove a gap.
+    const routeCoverage: boolean[] = [];
+    let inferredProbeCount = 0;
+    const outcome = () => ({
+      collection: latestCollection,
+      coverageConfirmed: routeCoverage.every(Boolean),
+      inferredProbeCount,
+    });
 
     for (const client of Array.from(this.clients.values())) {
       if (routeMatches && !routeMatches(client)) continue;
@@ -3091,13 +3209,29 @@ export class LspManager {
         serverConfig.fileTypes,
       ).slice(0, 24);
 
+      // Marker roots whose program an earlier candidate already loaded.
+      const coveredRoots = new Set<string>();
+      let routeInferred = false;
       for (const target of warmTargets) {
+        if (coveredRoots.has(target.projectRoot)) continue;
         // A file probe does not load every program under the route root.
         const fileKey = `${client.name}:${path.resolve(target.file)}`;
-        if (this.warmedWorkspaceSymbolFiles.has(fileKey)) continue;
+        const previous = this.warmedWorkspaceSymbolFiles.get(fileKey);
+        if (previous === "inferred") {
+          routeInferred = true;
+          inferredProbeCount++;
+          continue;
+        }
+        if (previous !== undefined) {
+          coveredRoots.add(target.projectRoot);
+          continue;
+        }
 
-        const openedClient = await this.ensureFileOpen(target.file);
-        if (!openedClient) continue;
+        const openedClient = await this.ensureFileOpen(target.file, { control });
+        if (!openedClient) {
+          this.recordWarmProbeEvent(client.name, target.file, "open-failed", control);
+          continue;
+        }
 
         // A cancelled pass must not mark projects warmed on its way out.
         throwIfCodeRequestInterrupted(control);
@@ -3107,32 +3241,84 @@ export class LspManager {
           getWarmPosition,
           control,
         );
-        if (available) {
-          this.warmedWorkspaceSymbolFiles.add(fileKey);
-          warmedAny = true;
+        if (!available) {
+          this.recordWarmProbeEvent(client.name, target.file, "probe-unavailable", control);
+          continue;
+        }
+        const membership = await openedClient.projectMembership(target.file, control);
+        throwIfCodeRequestInterrupted(control);
+        this.warmedWorkspaceSymbolFiles.set(fileKey, membership);
+        this.recordWarmProbeEvent(client.name, target.file, membership, control);
+        if (membership === "inferred") {
+          // The file loaded only its own inferred project; workspace/symbol
+          // still cannot see the configured program, so try the next file
+          // without collecting: a hit here could come from that inferred
+          // project alone and would hide the configured program's rows.
+          routeInferred = true;
+          inferredProbeCount++;
+          continue;
         }
 
+        coveredRoots.add(target.projectRoot);
         latestCollection = await collect(this.clients.values(), query);
-        if (latestCollection.hasSupport && latestCollection.results.length > 0) {
-          return { warmedAny, collection: latestCollection };
+        if (hasResult(latestCollection)) {
+          return { ...outcome(), coverageConfirmed: true };
         }
       }
+      routeCoverage.push(coveredRoots.size > 0 || !routeInferred);
     }
 
+    if (inferredProbeCount > 0 && latestCollection === null) {
+      latestCollection = await collect(this.clients.values(), query);
+    }
     // A completed-empty retry replaces an earlier failure too.
-    return { warmedAny, collection: latestCollection };
+    return outcome();
+  }
+
+  /**
+   * Record one workspace-symbol warm-up probe: which file was opened and
+   * whether the server placed it in a configured project. `unknown` means the
+   * route cannot report membership (non-TypeScript or native TS7).
+   */
+  private recordWarmProbeEvent(
+    serverName: string,
+    file: string,
+    outcome: ProjectMembership | "open-failed" | "probe-unavailable",
+    control?: CodeRequestControl,
+  ): void {
+    try {
+      recordDebugEvent({
+        operationId: control?.operationId,
+        source: "lsp",
+        level: "debug",
+        category: "workspace-symbol.warm-probe",
+        message: `Workspace-symbol warm-up probe: ${outcome}`,
+        cwd: boundCwd(this.cwd),
+        data: {
+          server: truncateIdentity(serverName),
+          file: truncateIdentity(displayRelativeFilePath(file, this.cwd)),
+          outcome,
+        },
+      });
+    } catch {
+      // Warm-up telemetry must never change query behavior.
+    }
   }
 
   private async warmSemanticProject(
     client: LspClient,
-    filePath: string,
+    filePath: string | readonly string[],
     preferExactFile: boolean = false,
     control?: CodeRequestControl,
   ): Promise<void> {
     const serverConfig = this.config.servers[client.name];
     if (!serverConfig) return;
 
-    const resolvedFile = resolveSessionPath(this.cwd, filePath);
+    const candidates = (typeof filePath === "string" ? [filePath] : filePath).map((file) =>
+      resolveSessionPath(this.cwd, file),
+    );
+    const resolvedFile = candidates[0];
+    if (!resolvedFile) return;
     const projectRoot = preferExactFile
       ? resolveRootForFile(resolvedFile, client.name, serverConfig.rootMarkers, {
           knownRoots: this.knownRoots,
@@ -3150,7 +3336,7 @@ export class LspManager {
       return;
     }
 
-    const probe = this.performWarmProbe(client, resolvedFile, projectKey, control);
+    const probe = this.performWarmProbe(client, candidates, projectKey, control);
     this.pendingWarmProbes.set(projectKey, probe);
     try {
       await raceRequestControl(probe, control);
@@ -3161,28 +3347,40 @@ export class LspManager {
     }
   }
 
+  /**
+   * Probe candidates in order until one loads a non-inferred project.
+   * The project is marked warmed after any successful probe so files that
+   * really sit in inferred projects are not reprobed on every request.
+   */
   private async performWarmProbe(
     client: LspClient,
-    resolvedFile: string,
+    candidates: readonly string[],
     projectKey: string,
     control?: CodeRequestControl,
   ): Promise<void> {
     const key = clientKey(client.name, client.root);
-    if (this.clients.get(key) !== client) return;
-    const openedClient = await this.ensureFileOpen(resolvedFile);
-    if (!openedClient || openedClient !== client || this.clients.get(key) !== client) return;
-
     // 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 available = await this.probeDocumentSymbols(
-      openedClient,
-      resolvedFile,
-      getWorkspaceSymbolWarmPosition,
-      sharedControl,
-    );
-    if (available && this.clients.get(key) === client) {
+    let warmed = false;
+    for (const [index, resolvedFile] of candidates.entries()) {
+      if (this.clients.get(key) !== client) return;
+      const openedClient = await this.ensureFileOpen(resolvedFile);
+      if (!openedClient || openedClient !== client || this.clients.get(key) !== client) continue;
+      const available = await this.probeDocumentSymbols(
+        openedClient,
+        resolvedFile,
+        getWorkspaceSymbolWarmPosition,
+        sharedControl,
+      );
+      if (!available) continue;
+      warmed = true;
+      if (index === candidates.length - 1) break;
+      const membership = await openedClient.projectMembership(resolvedFile, sharedControl);
+      if (membership !== "inferred") break;
+    }
+    if (warmed && this.clients.get(key) === client) {
       this.warmedSemanticProjects.add(projectKey);
     }
   }
@@ -3213,7 +3411,7 @@ export class LspManager {
 
   private clearWarmedWorkspaceSymbolFiles(serverName: string, root: string): void {
     const prefix = `${serverName}:${path.resolve(root)}`;
-    for (const key of Array.from(this.warmedWorkspaceSymbolFiles)) {
+    for (const key of Array.from(this.warmedWorkspaceSymbolFiles.keys())) {
       if (key === prefix || key.startsWith(`${prefix}${path.sep}`)) {
         this.warmedWorkspaceSymbolFiles.delete(key);
       }

package/src/session/runtime-registry.ts

@@ -139,6 +139,8 @@ function recordScopeDecisionEvent(manager: LspManager): void {
   }
 }
 
+const FILE_STARTUP_FAILURE_REASON = "The routed LSP client could not be started for this file";
+
 class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   constructor(private readonly manager: LspManager) {}
 
@@ -157,6 +159,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("hover", resolvedPath);
@@ -171,6 +174,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("definition", resolvedPath);
@@ -185,6 +189,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("references", resolvedPath);
@@ -202,6 +207,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("implementation", resolvedPath);
@@ -215,6 +221,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("document symbols", resolvedPath);
@@ -260,6 +267,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return null;
@@ -309,7 +317,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       const processCrashRecovery = this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
       return {
         kind: "unavailable",
-        reason: "No LSP client can serve this file",
+        reason: this.fileUnavailableReason(resolvedPath, "No LSP client can serve this file"),
         ...(processCrashRecovery ? { processCrashRecovery } : {}),
       };
     }
@@ -347,7 +355,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     if (!client) {
       return {
         kind: "unavailable",
-        reason: "The routed LSP client could not be started for this file",
+        reason: this.fileUnavailableReason(resolvedPath, FILE_STARTUP_FAILURE_REASON),
         ...startup,
         ...recovery,
       };
@@ -355,6 +363,15 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     return { kind: "ready", ...startup, ...recovery };
   }
 
+  private fileUnavailableReason(filePath: string, configuredRouteReason: string): string {
+    if (!this.manager.hasConfiguredServerForFile(filePath)) {
+      return "No compatible LSP server is configured for this file";
+    }
+    return this.manager.hasFailedStartupForFile(filePath)
+      ? FILE_STARTUP_FAILURE_REASON
+      : configuredRouteReason;
+  }
+
   /**
    * Wait until all started LSP clients are ready for semantic queries.
    * Performs one representative warm-up probe per client/root.

package/src/session/runtime-rename.ts

@@ -21,6 +21,7 @@ export async function runRoutedRename(options: {
   const { manager, file, position, newName, control } = options;
   const client = await manager.ensureFileOpen(file, {
     recoverProcessCrash: true,
+    protectInputs: true,
     control,
   });
   if (!client) return null;

package/src/session/workspace-lsp-runtime.ts

@@ -143,7 +143,11 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
     filePath: string,
     control?: CodeRequestControl,
   ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>>;
-  /** Collect symbols from routes that can contribute within the optional path scopes. */
+  /**
+   * Collect symbols from contributing routes; completeness is relative to scopes.
+   * Data may include out-of-scope rows, which callers must filter themselves.
+   * Only policy exclusions proven outside every scope are irrelevant to completeness.
+   */
   workspaceSymbol(
     query: string,
     control?: CodeRequestControl,