@mrclrchtr/supi-code-intelligence 1.3.1 → 1.4.0

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

@@ -4,7 +4,16 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as projectRoots from "@mrclrchtr/supi-core/api";
 import { LspClient } from "../client/client.ts";
-import { getServerForFile } from "../config.ts";
+import { getServerForFile } from "../config/config.ts";
+import type {
+  DetectedProjectServer,
+  Diagnostic,
+  FileEvent,
+  LspConfig,
+  ProjectServerInfo,
+  SymbolInformation,
+  WorkspaceSymbol,
+} from "../config/types.ts";
 import {
   accumulateOutstandingDiagnostics,
   collectDiagnosticSummaryCounts,
@@ -19,14 +28,7 @@ import {
   normalizeRelevantPaths,
   shouldIgnoreLspPath,
 } from "../summary.ts";
-import type {
-  DetectedProjectServer,
-  Diagnostic,
-  FileEvent,
-  LspConfig,
-  ProjectServerInfo,
-} from "../types.ts";
-import { commandExists } from "../utils.ts";
+import { commandExists, resolveSessionPath } from "../utils.ts";
 import {
   closeFileAcrossClients,
   pruneMissingFilesFromClients,
@@ -53,12 +55,15 @@ import type {
   ServerStatus,
 } from "./manager-types.ts";
 import { recoverWorkspaceDiagnostics as recoverWorkspaceDiagnosticsImpl } from "./manager-workspace-recovery.ts";
+
+type UnavailableReason = "missing-command" | "start-failed" | "runtime-error";
+
 // ── LspManager ────────────────────────────────────────────────────────
 export class LspManager {
   /** Active clients keyed by "serverName:root" */
   private clients = new Map<string, LspClient>();
-  /** Servers we've already tried and failed to start */
-  private unavailable = new Set<string>();
+  /** Per-root startup failures keyed by "serverName:root" */
+  private unavailable = new Map<string, UnavailableReason>();
   /** Memoized per-command availability of LSP server binaries on PATH */
   private commandAvailability = new Map<string, boolean>();
   /** Guards against concurrent client creation for the same server:root key */
@@ -67,6 +72,8 @@ export class LspManager {
   private knownRoots = new Map<string, string[]>();
   /** User-configured gitignore-style exclude patterns */
   private excludePatterns: string[] = [];
+  /** Project roots already warmed for workspace-symbol queries. */
+  private warmedWorkspaceSymbolProjects = new Set<string>();
   constructor(
     private readonly config: LspConfig,
     private readonly cwd: string,
@@ -80,32 +87,43 @@ export class LspManager {
 
   /** Check whether any configured language server handles the given file's extension. */
   hasServerForExtension(filePath: string): boolean {
-    return getServerForFile(this.config, filePath) !== null;
+    return getServerForFile(this.config, resolveSessionPath(this.cwd, filePath)) !== null;
   }
   // ── Public API ────────────────────────────────────────────────────
   registerDetectedServers(detected: DetectedProjectServer[]): void {
     this.knownRoots = projectRoots.buildKnownRootsMap(detected);
   }
-  /** Check whether a file path has an available LSP server. */
-  isSupportedSourceFile(filePath: string): boolean {
-    // Dependency directories are intentionally excluded from recent-path
-    // tracking and diagnostic summaries (shouldIgnoreLspPath). Keep runtime
-    // guidance activation consistent: reading or editing a file under
-    // node_modules / .pnpm must not arm LSP guidance for dependency sources.
-    if (shouldIgnoreLspPath(filePath, this.cwd)) return false;
-    const match = getServerForFile(this.config, filePath);
+  /** Check whether a file path has an available LSP server for explicit semantic operations. */
+  canServeFile(filePath: string): boolean {
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
+    const match = getServerForFile(this.config, resolvedPath);
     if (!match) return false;
     const [serverName, serverConfig] = match;
     // Mirror getClientForFile's root resolution so the unavailable check stays
     // root-specific. A failed startup in one workspace must not suppress
     // activation for unrelated roots served by the same language server.
-    const root = resolveRootForFile(filePath, serverName, serverConfig.rootMarkers, {
+    const root = resolveRootForFile(resolvedPath, serverName, serverConfig.rootMarkers, {
       knownRoots: this.knownRoots,
       cwd: this.cwd,
     });
-    if (this.unavailable.has(`${serverName}:${root}`)) return false;
+    const key = clientKey(serverName, root);
+    if (this.getUnavailableReason(key, serverConfig.command)) return false;
     return this.isServerCommandAvailable(serverConfig.command);
   }
+
+  /**
+   * Check whether a file should participate in runtime guidance and diagnostics.
+   * This is stricter than {@link canServeFile} and intentionally filters dependency
+   * and tsconfig-excluded paths from UI/context behavior.
+   */
+  isSupportedSourceFile(filePath: string): boolean {
+    // Dependency directories are intentionally excluded from recent-path
+    // tracking and diagnostic summaries (shouldIgnoreLspPath). Keep runtime
+    // guidance activation consistent: reading or editing a file under
+    // node_modules / .pnpm must not arm LSP guidance for dependency sources.
+    if (shouldIgnoreLspPath(filePath, this.cwd)) return false;
+    return this.canServeFile(filePath);
+  }
   private isServerCommandAvailable(command: string): boolean {
     // Only memoize positive lookups. A negative result may become stale if the
     // user installs the binary mid-session (e.g. `mise install`), and
@@ -117,12 +135,25 @@ export class LspManager {
     if (available) this.commandAvailability.set(command, true);
     return available;
   }
+
+  private getUnavailableReason(key: string, command?: string): UnavailableReason | null {
+    const reason = this.unavailable.get(key);
+    if (!reason) return null;
+
+    if (reason === "missing-command" && command && this.isServerCommandAvailable(command)) {
+      this.unavailable.delete(key);
+      return null;
+    }
+
+    return reason;
+  }
   /** Get or create an LSP client for the given file. */
   async getClientForFile(filePath: string): Promise<LspClient | null> {
-    const match = getServerForFile(this.config, filePath);
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
+    const match = getServerForFile(this.config, resolvedPath);
     if (!match) return null;
     const [serverName, serverConfig] = match;
-    const root = resolveRootForFile(filePath, serverName, serverConfig.rootMarkers, {
+    const root = resolveRootForFile(resolvedPath, serverName, serverConfig.rootMarkers, {
       knownRoots: this.knownRoots,
       cwd: this.cwd,
     });
@@ -132,7 +163,7 @@ export class LspManager {
     const serverConfig = this.config.servers[serverName];
     if (!serverConfig) return null;
     const key = clientKey(serverName, root);
-    if (this.unavailable.has(key)) return null;
+    if (this.getUnavailableReason(key, serverConfig.command)) return null;
 
     // Return existing client
     const existing = this.clients.get(key);
@@ -141,7 +172,8 @@ export class LspManager {
     // If existing client errored, remove it
     if (existing && existing.status === "error") {
       this.clients.delete(key);
-      this.unavailable.add(key);
+      this.unavailable.set(key, "runtime-error");
+      this.clearWarmedWorkspaceSymbolProjects(existing.name, existing.root);
       return null;
     }
 
@@ -168,25 +200,27 @@ export class LspManager {
    */
   private async performStart(
     serverName: string,
-    serverConfig: import("../types.ts").ServerConfig,
+    serverConfig: import("../config/types.ts").ServerConfig,
     root: string,
     key: string,
   ): Promise<LspClient | null> {
     // Validate command exists
     if (!commandExists(serverConfig.command)) {
-      this.unavailable.add(key);
+      this.unavailable.set(key, "missing-command");
       return null;
     }
 
     // Spawn new client
     const client = new LspClient(serverName, serverConfig, root);
+    this.clearWarmedWorkspaceSymbolProjects(serverName, root);
     this.clients.set(key, client);
     rememberKnownRoot(this.knownRoots, serverName, root);
     try {
       await client.start();
+      this.unavailable.delete(key);
       return client;
     } catch {
-      this.unavailable.add(key);
+      this.unavailable.set(key, "start-failed");
       this.clients.delete(key);
       return null;
     }
@@ -194,10 +228,11 @@ export class LspManager {
 
   /** Find an already-started client for a file without spawning a new server. */
   private getExistingClientForFile(filePath: string): LspClient | null {
-    const match = getServerForFile(this.config, filePath);
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
+    const match = getServerForFile(this.config, resolvedPath);
     if (!match) return null;
     const [serverName, serverConfig] = match;
-    const root = resolveRootForFile(filePath, serverName, serverConfig.rootMarkers, {
+    const root = resolveRootForFile(resolvedPath, serverName, serverConfig.rootMarkers, {
       knownRoots: this.knownRoots,
       cwd: this.cwd,
     });
@@ -210,7 +245,7 @@ export class LspManager {
     const seen = new Set<string>();
 
     for (const filePath of filePaths) {
-      const resolvedPath = path.resolve(this.cwd, filePath);
+      const resolvedPath = resolveSessionPath(this.cwd, filePath);
       const client = this.getExistingClientForFile(resolvedPath);
       if (!client) continue;
 
@@ -240,6 +275,7 @@ export class LspManager {
 
     this.clients.delete(key);
     this.unavailable.delete(key);
+    this.clearWarmedWorkspaceSymbolProjects(client.name, client.root);
 
     const replacement = new LspClient(client.name, serverConfig, client.root);
     this.clients.set(key, replacement);
@@ -258,7 +294,7 @@ export class LspManager {
       return true;
     } catch {
       this.clients.delete(key);
-      this.unavailable.add(key);
+      this.unavailable.set(key, "start-failed");
       return false;
     }
   }
@@ -271,7 +307,8 @@ export class LspManager {
         root,
         fileTypes,
         client: this.clients.get(key),
-        unavailable: this.unavailable.has(key),
+        unavailableReason:
+          this.getUnavailableReason(key, this.config.servers[serverName]?.command) ?? undefined,
       },
       this.cwd,
     );
@@ -303,7 +340,7 @@ export class LspManager {
     filePath: string,
     maxSeverity: number = 1,
   ): Promise<Diagnostic[]> {
-    const resolvedPath = path.resolve(filePath);
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
     return (
       (await this.syncFileAndGetCascadingDiagnostics(resolvedPath, maxSeverity)).find(
         (entry) => entry.file === resolvedPath,
@@ -314,9 +351,9 @@ export class LspManager {
     filePath: string,
     maxSeverity: number = 1,
   ): Promise<Array<{ file: string; diagnostics: Diagnostic[] }>> {
-    const client = await this.getClientForFile(filePath);
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
+    const client = await this.getClientForFile(resolvedPath);
     if (!client) return [];
-    const resolvedPath = path.resolve(filePath);
     try {
       const { primary, cascade } = await syncClientFileAndGetCascadingDiagnostics(
         client,
@@ -334,7 +371,7 @@ export class LspManager {
   }
   /** Close a file across any active LSP clients and clear its cached diagnostics. */
   closeFile(filePath: string): void {
-    closeFileAcrossClients(this.clients.values(), filePath);
+    closeFileAcrossClients(this.clients.values(), resolveSessionPath(this.cwd, filePath));
   }
   /** Remove any missing files from open-document and diagnostic state. */
   pruneMissingFiles(): string[] {
@@ -384,6 +421,7 @@ export class LspManager {
     this.clients.clear();
     this.unavailable.clear();
     this.knownRoots.clear();
+    this.warmedWorkspaceSymbolProjects.clear();
   }
   /** Get status of all servers. */
   getStatus(): ManagerStatus {
@@ -529,15 +567,30 @@ export class LspManager {
       maxSeverity,
     );
   }
-  async workspaceSymbol(query: string) {
-    return (await import("./manager-workspace-symbol.ts")).managerWorkspaceSymbol(
-      this.clients.values(),
+  async workspaceSymbol(query: string): Promise<(SymbolInformation | WorkspaceSymbol)[] | null> {
+    const helper = await import("./manager-workspace-symbol.ts");
+    const initial = await helper.collectWorkspaceSymbols(this.clients.values(), query);
+    if (!initial.hasSupport) return null;
+    if (initial.results.length > 0) return initial.results;
+
+    const warmed = await this.warmWorkspaceSymbolProjectsUntilResult(
+      helper.findWorkspaceSymbolWarmTargets,
+      helper.getWorkspaceSymbolWarmPosition,
+      helper.collectWorkspaceSymbols,
       query,
     );
+    if (warmed.results) return warmed.results;
+    if (!warmed.warmedAny) return initial.results;
+
+    return this.retryWorkspaceSymbolAfterWarmup(
+      helper.collectWorkspaceSymbols,
+      query,
+      initial.results,
+    );
   }
   async ensureFileOpen(filePath: string): Promise<LspClient | null> {
-    const client = await this.getClientForFile(filePath);
-    const resolvedPath = path.resolve(filePath);
+    const resolvedPath = resolveSessionPath(this.cwd, filePath);
+    const client = await this.getClientForFile(resolvedPath);
     if (!client) return null;
     try {
       client.didOpen(resolvedPath, fs.readFileSync(resolvedPath, "utf-8"));
@@ -547,4 +600,110 @@ export class LspManager {
       return null;
     }
   }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: warm-up coordinates client/project iteration, targeted semantic nudges, and early-return queries in one place.
+  private async warmWorkspaceSymbolProjectsUntilResult(
+    findWarmTargets: (
+      root: string,
+      rootMarkers: string[],
+      fileTypes: string[],
+    ) => Array<{ projectRoot: string; file: string }>,
+    getWarmPosition: (
+      symbols: Awaited<ReturnType<LspClient["documentSymbols"]>>,
+    ) => import("../config/types.ts").Position | null,
+    collect: (
+      clients: Iterable<LspClient>,
+      query: string,
+    ) => Promise<{ results: (SymbolInformation | WorkspaceSymbol)[]; hasSupport: boolean }>,
+    query: string,
+  ): Promise<{ warmedAny: boolean; results: (SymbolInformation | WorkspaceSymbol)[] | null }> {
+    let warmedAny = false;
+
+    for (const client of Array.from(this.clients.values())) {
+      if (client.status !== "running") continue;
+      if (!client.serverCapabilities?.workspaceSymbolProvider) continue;
+
+      const serverConfig = this.config.servers[client.name];
+      if (!serverConfig) continue;
+
+      const warmTargets = findWarmTargets(
+        client.root,
+        serverConfig.rootMarkers,
+        serverConfig.fileTypes,
+      ).slice(0, 24);
+
+      for (const target of warmTargets) {
+        const projectKey = this.workspaceSymbolProjectKey(client.name, target.projectRoot);
+        if (this.warmedWorkspaceSymbolProjects.has(projectKey)) continue;
+        if (this.hasOpenFileInProject(client, target.projectRoot)) {
+          this.warmedWorkspaceSymbolProjects.add(projectKey);
+          continue;
+        }
+
+        const openedClient = await this.ensureFileOpen(target.file);
+        if (!openedClient) continue;
+
+        this.warmedWorkspaceSymbolProjects.add(projectKey);
+        warmedAny = true;
+
+        try {
+          const symbols = await openedClient.documentSymbols(target.file);
+          const hoverPosition = getWarmPosition(symbols);
+          if (hoverPosition) {
+            await openedClient.hover(target.file, hoverPosition);
+          }
+        } catch {
+          // Best-effort warm-up only.
+        }
+
+        const collected = await collect(this.clients.values(), query);
+        if (collected.hasSupport && collected.results.length > 0) {
+          return { warmedAny, results: collected.results };
+        }
+      }
+    }
+
+    return { warmedAny, results: null };
+  }
+
+  private async retryWorkspaceSymbolAfterWarmup(
+    collect: (
+      clients: Iterable<LspClient>,
+      query: string,
+    ) => Promise<{ results: (SymbolInformation | WorkspaceSymbol)[]; hasSupport: boolean }>,
+    query: string,
+    fallbackResults: (SymbolInformation | WorkspaceSymbol)[],
+  ): Promise<(SymbolInformation | WorkspaceSymbol)[]> {
+    const attempts = 5;
+    const delayMs = 50;
+
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      if (attempt > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+      const retried = await collect(this.clients.values(), query);
+      if (!retried.hasSupport || retried.results.length > 0) {
+        return retried.hasSupport ? retried.results : fallbackResults;
+      }
+    }
+
+    return fallbackResults;
+  }
+
+  private hasOpenFileInProject(client: LspClient, projectRoot: string): boolean {
+    return client.openFiles.some((openFile) => projectRoots.isWithinOrEqual(projectRoot, openFile));
+  }
+
+  private workspaceSymbolProjectKey(serverName: string, projectRoot: string): string {
+    return `${serverName}:${path.resolve(projectRoot)}`;
+  }
+
+  private clearWarmedWorkspaceSymbolProjects(serverName: string, root: string): void {
+    const prefix = `${serverName}:${path.resolve(root)}`;
+    for (const key of Array.from(this.warmedWorkspaceSymbolProjects)) {
+      if (key === prefix || key.startsWith(`${prefix}${path.sep}`)) {
+        this.warmedWorkspaceSymbolProjects.delete(key);
+      }
+    }
+  }
 }

package/node_modules/@mrclrchtr/supi-lsp/src/{lsp-state.ts → session/lsp-state.ts}

@@ -2,11 +2,12 @@
 // Extracted from lsp.ts to keep file sizes within Biome limits.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { LspManager } from "./manager/manager.ts";
+import type { DetectedProjectServer, ProjectServerInfo } from "../config/types.ts";
+import type { LspManager } from "../manager/manager.ts";
+import { LSP_TOOL_NAMES } from "../tool/names.ts";
+import type { LspInspectorState } from "../ui/ui.ts";
 import { introspectCapabilities } from "./scanner.ts";
 import { clearSessionLspService } from "./service-registry.ts";
-import type { DetectedProjectServer, ProjectServerInfo } from "./types.ts";
-import type { LspInspectorState } from "./ui.ts";
 
 export interface LspRuntimeState {
   manager: LspManager | null;
@@ -49,7 +50,12 @@ export function refreshProjectServers(state: LspRuntimeState): void {
 }
 
 export function isLspAwareTool(toolName: string): boolean {
-  return toolName === "lsp" || toolName === "read" || toolName === "write" || toolName === "edit";
+  return (
+    LSP_TOOL_NAMES.includes(toolName as (typeof LSP_TOOL_NAMES)[number]) ||
+    toolName === "read" ||
+    toolName === "write" ||
+    toolName === "edit"
+  );
 }
 
 export function disableLspState(pi: ExtensionAPI, state: LspRuntimeState): void {
@@ -66,17 +72,22 @@ export function disableLspState(pi: ExtensionAPI, state: LspRuntimeState): void
   state.lastWorkspaceChangeAt = 0;
   state.sentinelSnapshot = new Map();
   state.lspActive = false;
-  removeLspTool(pi);
+  removeLspTools(pi);
 }
 
-export function removeLspTool(pi: ExtensionAPI): void {
+export function removeLspTools(pi: ExtensionAPI): void {
   const activeTools = pi.getActiveTools();
-  if (activeTools.includes("lsp"))
-    pi.setActiveTools(activeTools.filter((t: string) => t !== "lsp"));
+  const nextTools = activeTools.filter(
+    (toolName: string) => !LSP_TOOL_NAMES.includes(toolName as (typeof LSP_TOOL_NAMES)[number]),
+  );
+  if (nextTools.length !== activeTools.length) {
+    pi.setActiveTools(nextTools);
+  }
 }
 
-export function ensureLspToolActive(pi: ExtensionAPI): void {
+export function ensureLspToolsActive(pi: ExtensionAPI): void {
   const activeTools = pi.getActiveTools();
-  if (activeTools.includes("lsp")) return;
-  pi.setActiveTools([...activeTools, "lsp"]);
+  const missing = LSP_TOOL_NAMES.filter((toolName) => !activeTools.includes(toolName));
+  if (missing.length === 0) return;
+  pi.setActiveTools([...activeTools, ...missing]);
 }

package/node_modules/@mrclrchtr/supi-lsp/src/{scanner.ts → session/scanner.ts}

@@ -1,15 +1,15 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { dedupeTopmostRoots, walkProject } from "@mrclrchtr/supi-core/api";
-import type { LspManager } from "./manager/manager.ts";
 import type {
   DetectedProjectServer,
   LspConfig,
   MissingServer,
   ProjectServerInfo,
   ServerConfig,
-} from "./types.ts";
-import { commandExists } from "./utils.ts";
+} from "../config/types.ts";
+import type { LspManager } from "../manager/manager.ts";
+import { commandExists } from "../utils.ts";
 
 const DEFAULT_MAX_DEPTH = 3;
 

package/node_modules/@mrclrchtr/supi-lsp/src/{service-registry.ts → session/service-registry.ts}

@@ -3,8 +3,8 @@
 // to reuse the active LSP runtime without starting duplicate servers.
 
 import * as path from "node:path";
-import type { LspManager } from "./manager/manager.ts";
 import type {
+  CodeAction,
   Diagnostic,
   DocumentSymbol,
   Hover,
@@ -13,11 +13,43 @@ import type {
   Position,
   ProjectServerInfo,
   SymbolInformation,
+  WorkspaceEdit,
   WorkspaceSymbol,
-} from "./types.ts";
+} from "../config/types.ts";
+import type { LspManager } from "../manager/manager.ts";
+import { resolveSessionPath } from "../utils.ts";
+
+/** Workspace diagnostic summary grouped by file. */
+export interface WorkspaceDiagnosticSummaryEntry {
+  file: string;
+  errors: number;
+  warnings: number;
+}
+
+/** Outstanding diagnostics grouped by file, including info and hint counts. */
+export interface OutstandingDiagnosticSummaryEntry {
+  file: string;
+  total: number;
+  errors: number;
+  warnings: number;
+  information: number;
+  hints: number;
+}
+
+/** Result from a workspace diagnostic recovery pass. */
+export interface RecoverDiagnosticsResult {
+  refreshedClients: number;
+  restartedClients: number;
+  staleAssessment: {
+    suspected: boolean;
+    matchedFiles: Array<{ file: string; diagnostics: Diagnostic[] }>;
+    warning: string | null;
+  };
+}
 
 export type SessionLspServiceState =
   | { kind: "ready"; service: SessionLspService }
+  | { kind: "inactive"; service: SessionLspService }
   | { kind: "pending" }
   | { kind: "disabled" }
   | { kind: "unavailable"; reason: string };
@@ -25,7 +57,9 @@ export type SessionLspServiceState =
 /**
  * Public wrapper around {@link LspManager} that exposes stable semantic operations.
  * File path inputs may be absolute or session-cwd-relative; a leading `@` is stripped
- * to match pi's built-in path-tool convention.
+ * to match pi's built-in path-tool convention. Position arguments use raw 0-based LSP
+ * coordinates; use `toLspPosition()` from `@mrclrchtr/supi-lsp/api` when starting from
+ * user-facing 1-based line and character values.
  */
 export class SessionLspService {
   constructor(private readonly manager: LspManager) {}
@@ -77,44 +111,86 @@ export class SessionLspService {
     return this.manager.workspaceSymbol(query);
   }
 
+  async rename(
+    filePath: string,
+    position: Position,
+    newName: string,
+  ): Promise<WorkspaceEdit | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    const client = await this.manager.ensureFileOpen(resolvedPath);
+    if (!client) return null;
+    return client.rename(resolvedPath, position, newName);
+  }
+
+  async codeActions(filePath: string, position: Position): Promise<CodeAction[] | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    const client = await this.manager.ensureFileOpen(resolvedPath);
+    if (!client) return null;
+
+    const range = { start: position, end: position };
+    const diagnostics = client
+      .getDiagnostics(resolvedPath)
+      .filter((diagnostic) => diagnostic.range.start.line <= position.line)
+      .filter((diagnostic) => diagnostic.range.end.line >= position.line);
+
+    return client.codeActions(resolvedPath, range, { diagnostics });
+  }
+
   // ── Project / runtime awareness ─────────────────────────────────────
 
   getProjectServers(): ProjectServerInfo[] {
     return this.manager.getKnownProjectServers([]);
   }
 
+  /** Check whether the file can be served semantically for explicit LSP operations. */
   isSupportedSourceFile(filePath: string): boolean {
-    return this.manager.isSupportedSourceFile(this.resolveFilePath(filePath));
+    return this.manager.canServeFile(this.resolveFilePath(filePath));
   }
 
   // ── Diagnostics ─────────────────────────────────────────────────────
 
+  /** Sync a file through LSP and return diagnostics up to the supplied severity threshold. */
+  async fileDiagnostics(filePath: string, maxSeverity: number = 4): Promise<Diagnostic[] | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    if (!this.manager.canServeFile(resolvedPath)) return null;
+    return this.manager.syncFileAndGetDiagnostics(resolvedPath, maxSeverity);
+  }
+
+  /** Get a lightweight workspace diagnostic summary for all tracked files. */
+  getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSummaryEntry[] {
+    return this.manager.getDiagnosticSummary();
+  }
+
+  /** Get outstanding diagnostics grouped by file at or above the supplied severity threshold. */
   getOutstandingDiagnostics(
     maxSeverity: number = 1,
   ): Array<{ file: string; diagnostics: Diagnostic[] }> {
     return this.manager.getOutstandingDiagnostics(maxSeverity);
   }
 
-  getOutstandingDiagnosticSummary(
-    maxSeverity: number = 1,
-  ): import("./manager/manager-types.ts").OutstandingDiagnosticSummaryEntry[] {
+  /** Get outstanding diagnostic counts grouped by file. */
+  getOutstandingDiagnosticSummary(maxSeverity: number = 1): OutstandingDiagnosticSummaryEntry[] {
     return this.manager.getOutstandingDiagnosticSummary(maxSeverity);
   }
 
-  /** Access the underlying manager for advanced use cases (discouraged). */
-  getManager(): LspManager {
-    return this.manager;
+  /** Trigger a workspace-wide diagnostics refresh and stale-state recovery pass. */
+  async recoverDiagnostics(options?: {
+    restartIfStillStale?: boolean;
+    maxWaitMs?: number;
+    quietMs?: number;
+  }): Promise<RecoverDiagnosticsResult> {
+    return this.manager.recoverWorkspaceDiagnostics(options);
   }
 
   private resolveFilePath(filePath: string): string {
-    const normalizedPath = filePath.startsWith("@") ? filePath.slice(1) : filePath;
-    return path.resolve(this.manager.getCwd(), normalizedPath);
+    return resolveSessionPath(this.manager.getCwd(), filePath);
   }
 }
 
 // ── Registry ──────────────────────────────────────────────────────────
 
 const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-lsp/session-registry");
+const WAIT_INTERVAL_MS = 25;
 
 function getRegistry(): Map<string, SessionLspServiceState> {
   const globalScope = globalThis as typeof globalThis & Record<symbol, unknown>;
@@ -147,6 +223,22 @@ export function getSessionLspService(cwd: string): SessionLspServiceState {
   );
 }
 
+/** Wait briefly for a pending session-scoped LSP service to become ready. */
+export async function waitForSessionLspService(
+  cwd: string,
+  timeoutMs: number = 250,
+): Promise<SessionLspServiceState> {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let state = getSessionLspService(cwd);
+
+  while (state.kind === "pending" && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
+    state = getSessionLspService(cwd);
+  }
+
+  return state;
+}
+
 /** Remove the LSP service state for a session cwd. */
 export function clearSessionLspService(cwd: string): void {
   registry.delete(normalizeCwd(cwd));