@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/analysis/evidence.ts

@@ -11,14 +11,24 @@
  * evidence-list primitive beneath it.
  */
 
-export type EvidencePartialReason = "timeout" | "safety-limit" | "interrupted" | "provider-limited";
+export type EvidencePartialReason =
+  | "timeout"
+  | "safety-limit"
+  | "interrupted"
+  | "provider-limited"
+  | "filesystem-error"
+  | "configuration-error"
+  | "invalid-provider-location";
 
 export interface EvidenceListMetadata {
   key: string;
   totalCount: number | null;
   shownCount: number;
+  /** Known collected atoms hidden by presentation; null when not tracked. */
   omittedCount: number | null;
   partialReason: EvidencePartialReason | null;
+  /** Unusable semantic-provider locations excluded from valid evidence totals. */
+  invalidLocationCount?: number;
 }
 
 export interface EvidenceList<T> {
@@ -38,6 +48,8 @@ export interface CreatePartialEvidenceListParams<T> {
   key: string;
   items: T[];
   partialReason: EvidencePartialReason;
+  /** Optional display cap; the overall evidence total remains unknown. */
+  maxResults?: number;
 }
 
 export interface EvidenceListSummary {
@@ -67,14 +79,17 @@ export function createEvidenceList<T>(params: CreateEvidenceListParams<T>): Evid
 export function createPartialEvidenceList<T>(
   params: CreatePartialEvidenceListParams<T>,
 ): EvidenceList<T> {
+  const maxResults = params.maxResults ?? params.items.length;
+  const items = params.items.slice(0, Math.max(0, maxResults));
   return {
     key: params.key,
-    items: [...params.items],
+    items,
     metadata: {
       key: params.key,
       totalCount: null,
-      shownCount: params.items.length,
-      omittedCount: null,
+      shownCount: items.length,
+      omittedCount:
+        params.maxResults === undefined ? null : Math.max(0, params.items.length - items.length),
       partialReason: params.partialReason,
     },
   };
@@ -89,7 +104,9 @@ export function renderEvidenceListMetadataDisclosure(
 ): string | null {
   if (metadata.totalCount === null) {
     if (metadata.partialReason === null) return null;
-    return `_(showing ${metadata.shownCount}; more may exist — ${metadata.partialReason})_`;
+    const omitted = metadata.omittedCount ?? 0;
+    const omittedDisclosure = omitted > 0 ? `; ${omitted} collected omitted` : "";
+    return `_(showing ${metadata.shownCount}${omittedDisclosure}; more may exist — ${metadata.partialReason})_`;
   }
 
   if ((metadata.omittedCount ?? 0) <= 0) return null;

package/src/analysis/health/diagnostics.ts

@@ -0,0 +1,183 @@
+// Diagnostics collection for code_health.
+// Extracted from orchestrate.ts.
+
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import type { Diagnostic, WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
+import type {
+  HealthDiagnosticEntry,
+  HealthDiagnosticMessage,
+  HealthDiagnosticObservation,
+  HealthDiagnosticScope,
+  HealthSection,
+} from "../../session/health-types.ts";
+
+// ── Diagnostics ───────────────────────────────────────────────────────
+
+export function isScopedFile(scopeFilter: string | null): scopeFilter is string {
+  return scopeFilter !== null && existsSync(scopeFilter) && !isDirectory(scopeFilter);
+}
+
+/** Describe exactly what a health diagnostic observation can establish. */
+export function diagnosticScope(scopeFilter: string | null): HealthDiagnosticScope {
+  return isScopedFile(scopeFilter)
+    ? { kind: "file", path: scopeFilter }
+    : { kind: "tracked-files", filter: scopeFilter };
+}
+
+interface CollectDiagnosticsOptions {
+  readonly service: WorkspaceLspRuntime | null;
+  readonly included: readonly HealthSection[];
+  readonly scope: HealthDiagnosticScope;
+  readonly cwd: string;
+  readonly unavailableReason: string;
+  /** Collect individual messages per file (detailed level). */
+  readonly detailed?: boolean;
+}
+
+/** Collect diagnostics without widening the requested evidence scope. */
+export async function collectDiagnostics(
+  options: CollectDiagnosticsOptions,
+): Promise<HealthDiagnosticObservation> {
+  const { service, included, scope, cwd, unavailableReason, detailed } = options;
+  if (!included.includes("diagnostics")) return { kind: "not-requested", entries: [] };
+  if (!service) return unavailableDiagnostics(scope, unavailableReason);
+
+  return scope.kind === "file"
+    ? collectScopedFileDiagnostics(service, scope, detailed)
+    : collectTrackedFileDiagnostics(service, scope, cwd, detailed);
+}
+
+async function collectScopedFileDiagnostics(
+  service: WorkspaceLspRuntime,
+  scope: Extract<HealthDiagnosticScope, { kind: "file" }>,
+  detailed?: boolean,
+): Promise<HealthDiagnosticObservation> {
+  try {
+    const result = await service.fileDiagnostics(scope.path, 4);
+    if (result.kind === "unavailable") return unavailableDiagnostics(scope, result.reason);
+
+    const entries = toFileDiagnosticEntries(scope.path, result.data, detailed);
+    return result.kind === "partial"
+      ? { kind: "partial", scope, entries, reason: result.reason }
+      : { kind: "completed", scope, entries };
+  } catch (error) {
+    return unavailableDiagnostics(scope, errorMessage(error, "File diagnostic request failed."));
+  }
+}
+
+function collectTrackedFileDiagnostics(
+  service: WorkspaceLspRuntime,
+  scope: Extract<HealthDiagnosticScope, { kind: "tracked-files" }>,
+  cwd: string,
+  detailed?: boolean,
+): HealthDiagnosticObservation {
+  try {
+    const entries = detailed
+      ? collectWorkspaceDiagnosticsDetailed(service, scope.filter, cwd)
+      : collectWorkspaceDiagnostics(service, scope.filter, cwd);
+    return { kind: "completed", scope, entries };
+  } catch (error) {
+    return unavailableDiagnostics(
+      scope,
+      errorMessage(error, "Tracked-file diagnostic snapshot is unavailable."),
+    );
+  }
+}
+
+function toFileDiagnosticEntries(
+  file: string,
+  diagnostics: ReadonlyArray<Pick<Diagnostic, "severity" | "message" | "source" | "range">>,
+  detailed?: boolean,
+): HealthDiagnosticEntry[] {
+  const errors = diagnostics.filter((diagnostic) => (diagnostic.severity ?? 1) === 1).length;
+  const warnings = diagnostics.filter((diagnostic) => (diagnostic.severity ?? 1) === 2).length;
+  if (!hasIssueCounts(errors, warnings)) return [];
+  const entry: HealthDiagnosticEntry = { file, errors, warnings };
+  if (detailed) {
+    return [{ ...entry, messages: extractMessages(diagnostics) }];
+  }
+  return [entry];
+}
+
+function collectWorkspaceDiagnostics(
+  service: WorkspaceLspRuntime,
+  scopeFilter: string | null,
+  cwd: string,
+): HealthDiagnosticEntry[] {
+  const summary = service.getWorkspaceDiagnosticSummary();
+  const result: HealthDiagnosticEntry[] = [];
+
+  for (const entry of summary) {
+    const filePath = resolve(cwd, entry.file);
+    if (scopeFilter && !isWithinOrEqual(scopeFilter, filePath)) continue;
+    if (!hasIssueCounts(entry.errors, entry.warnings)) continue;
+    result.push({ file: filePath, errors: entry.errors, warnings: entry.warnings });
+  }
+
+  return result;
+}
+
+/** Detailed workspace path: full diagnostics with messages, capped per file. */
+function collectWorkspaceDiagnosticsDetailed(
+  service: WorkspaceLspRuntime,
+  scopeFilter: string | null,
+  cwd: string,
+): HealthDiagnosticEntry[] {
+  const outstanding = service.getOutstandingDiagnostics(2);
+  const result: HealthDiagnosticEntry[] = [];
+
+  for (const { file, diagnostics } of outstanding) {
+    const filePath = resolve(cwd, file);
+    if (scopeFilter && !isWithinOrEqual(scopeFilter, filePath)) continue;
+    const entries = toFileDiagnosticEntries(filePath, diagnostics, true);
+    result.push(...entries);
+  }
+
+  return result;
+}
+
+// ── Message extraction ────────────────────────────────────────────────
+
+const MAX_MESSAGES_PER_FILE = 3;
+
+function extractMessages(
+  diagnostics: ReadonlyArray<Pick<Diagnostic, "severity" | "message" | "source" | "range">>,
+): HealthDiagnosticMessage[] {
+  const errorsAndWarnings = diagnostics
+    .filter((d) => (d.severity ?? 1) <= 2)
+    .sort(
+      (a, b) => (a.severity ?? 1) - (b.severity ?? 1) || a.range.start.line - b.range.start.line,
+    );
+
+  return errorsAndWarnings.slice(0, MAX_MESSAGES_PER_FILE).map((d) => ({
+    line: d.range.start.line + 1,
+    severity: (d.severity ?? 1) === 1 ? ("error" as const) : ("warning" as const),
+    message: typeof d.message === "string" ? d.message : d.message.value,
+    ...(d.source ? { source: d.source } : {}),
+  }));
+}
+
+function unavailableDiagnostics(
+  scope: HealthDiagnosticScope,
+  reason: string,
+): HealthDiagnosticObservation {
+  return { kind: "unavailable", scope, entries: [], reason };
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
+
+function hasIssueCounts(errors: number, warnings: number): boolean {
+  return errors > 0 || warnings > 0;
+}
+
+export function isDirectory(filePath: string): boolean {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/analysis/health/recovery.ts

@@ -0,0 +1,39 @@
+// Recovery and state description helpers for code_health.
+// Extracted from orchestrate.ts.
+
+import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
+import type { RecoverDiagnosticsResult, WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
+
+// ── Recovery ──────────────────────────────────────────────────────────
+
+interface RecoverOptions {
+  service: WorkspaceLspRuntime;
+  progress?: () => void;
+}
+
+/** Run the runtime's best-effort recovery and preserve its established outcome. */
+export async function recoverDiagnosticRuntime(
+  opts: RecoverOptions,
+): Promise<RecoverDiagnosticsResult> {
+  opts.progress?.();
+  return opts.service.recoverDiagnostics({ restartIfStillStale: true });
+}
+
+// ── State description helpers ─────────────────────────────────────────
+
+export function describeStructuralState(state: CapabilityState): string {
+  switch (state.kind) {
+    case "ready":
+      return "ready";
+    case "pending":
+      return "starting…";
+    case "inactive":
+      return "inactive";
+    case "disabled":
+      return "disabled by configuration";
+    case "unavailable":
+      return `unavailable — ${state.reason}`;
+    default:
+      return "unknown state";
+  }
+}

package/src/analysis/health/signals.ts

@@ -0,0 +1,20 @@
+// Live server collection for code_health.
+
+import type { WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
+import type { HealthData, HealthSection } from "../../session/health-types.ts";
+
+/** Collect the current language-server inventory when requested. */
+export function collectServers(
+  service: WorkspaceLspRuntime | null,
+  included: readonly HealthSection[],
+): HealthData["servers"] {
+  if (!included.includes("servers") || !service) return [];
+
+  return service.getProjectServers().map((server) => ({
+    name: server.name,
+    root: server.root,
+    fileTypes: server.fileTypes,
+    status: server.status,
+    ready: server.ready,
+  }));
+}

package/src/analysis/instruction-files.ts

@@ -1,6 +1,6 @@
 // Directory-local instruction file discovery and rendering for code_orientation.
 
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, realpathSync, statSync } from "node:fs";
 import * as path from "node:path";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
 
@@ -33,11 +33,30 @@ export interface InstructionFilesMetadata {
   files: Array<Omit<RenderedInstructionFile, "content">>;
 }
 
+/**
+ * Validate that a configured instruction file name is a plain filename
+ * with no directory components. Rejects names that would allow path traversal.
+ */
+export function isValidInstructionFileName(name: unknown): name is string {
+  if (typeof name !== "string") return false;
+  const trimmed = name.trim();
+  if (trimmed.length === 0 || trimmed !== name) return false;
+  if (trimmed !== path.basename(trimmed)) return false;
+  if (trimmed === "." || trimmed === "..") return false;
+  return true;
+}
+
 /**
  * Find configured instruction files for a directory focus.
  *
  * Walks from cwd to the focused directory (shallowest first, deepest last),
- * selecting the first configured file name that exists in each directory.
+ * selecting the first valid configured file name that exists in each directory.
+ * Each configured name is validated as a plain filename; resolved candidates
+ * are verified via realpath to remain within the workspace root.
+ *
+ * When the project is not trusted, all project-configured instruction files
+ * are rejected so a repository-authored path cannot cause reads outside the
+ * workspace root.
  */
 export function findInstructionFilesForDirectory(options: {
   directory: string;
@@ -45,11 +64,17 @@ export function findInstructionFilesForDirectory(options: {
   fileNames: string[];
   nativeContextPaths: Set<string>;
   surfacedDirectories: Set<string>;
+  /** Whether project-local configuration is trusted. */
+  projectTrusted: boolean;
 }): InstructionFileMatch[] {
   const cwd = path.resolve(options.cwd);
   const directory = path.resolve(options.directory);
-  const fileNames = options.fileNames.filter((name) => name.trim().length > 0);
-  if (fileNames.length === 0) return [];
+
+  const validNames =
+    options.projectTrusted && Array.isArray(options.fileNames)
+      ? options.fileNames.filter(isValidInstructionFileName)
+      : [];
+  if (validNames.length === 0) return [];
   if (!isDirectoryWithinCwd(directory, cwd)) return [];
 
   const dirs = collectDirsShallowestFirst(directory, cwd);
@@ -57,7 +82,7 @@ export function findInstructionFilesForDirectory(options: {
 
   for (const dir of dirs) {
     if (options.surfacedDirectories.has(dir)) continue;
-    const match = findFirstInstructionFile(dir, cwd, fileNames);
+    const match = findFirstInstructionFile(dir, cwd, validNames);
     if (!match) continue;
     if (options.nativeContextPaths.has(match.absolutePath)) continue;
     matches.push(match);
@@ -68,7 +93,9 @@ export function findInstructionFilesForDirectory(options: {
 
 function isDirectoryWithinCwd(directory: string, cwd: string): boolean {
   try {
-    return statSync(directory).isDirectory() && isWithinOrEqual(cwd, directory);
+    const realCwd = path.resolve(realpathSync(cwd));
+    const realDirectory = path.resolve(realpathSync(directory));
+    return statSync(realDirectory).isDirectory() && isWithinOrEqual(realCwd, realDirectory);
   } catch {
     return false;
   }
@@ -96,9 +123,30 @@ function findFirstInstructionFile(
 ): InstructionFileMatch | null {
   for (const fileName of fileNames) {
     const candidate = path.join(dir, fileName);
-    if (!isFile(candidate)) continue;
+
+    // Resolve the candidate to its real path to defuse symlinks that
+    // may point outside the workspace.
+    let realCandidate: string;
+    try {
+      realCandidate = path.resolve(realpathSync(candidate));
+    } catch {
+      continue;
+    }
+    if (!isFile(realCandidate)) continue;
+
+    // Verify containment: both the workspace root and the candidate must
+    // be resolved consistently so symlinks in temp directories (e.g. macOS
+    // /var → /private/var) don't break containment.
+    let realCwd: string;
+    try {
+      realCwd = path.resolve(realpathSync(cwd));
+    } catch {
+      continue;
+    }
+    if (!isWithinOrEqual(realCwd, realCandidate)) continue;
+
     return {
-      absolutePath: candidate,
+      absolutePath: realCandidate,
       relativePath: path.relative(cwd, candidate),
       directory: dir,
       relativeDirectory: path.relative(cwd, dir) || ".",
@@ -107,32 +155,15 @@ function findFirstInstructionFile(
   return null;
 }
 
-/** Render instruction files as a markdown section and structured metadata. */
-export function renderInstructionFiles(
+/** Read bounded instruction-file facts for session-owned Orientation. */
+export function collectInstructionFiles(
   files: InstructionFileMatch[],
   lineLimit = INSTRUCTION_FILE_LINE_LIMIT,
-): { markdown: string; metadata: InstructionFilesMetadata } | null {
+): { files: RenderedInstructionFile[]; metadata: InstructionFilesMetadata } | null {
   const rendered = files.map((file) => renderInstructionFile(file, lineLimit)).filter(isRendered);
   if (rendered.length === 0) return null;
-
-  const lines: string[] = [];
-  lines.push("## Instructions");
-  lines.push("");
-  for (const file of rendered) {
-    lines.push(`### ${file.path}`);
-    lines.push("");
-    lines.push(file.content);
-    if (file.truncated) {
-      lines.push("");
-      lines.push(
-        `_Instruction file truncated to ${file.shownLines} of ${file.totalLines} lines. Use \`read\` on \`${file.path}\` for the full file._`,
-      );
-    }
-    lines.push("");
-  }
-
   return {
-    markdown: lines.join("\n").trimEnd(),
+    files: rendered,
     metadata: {
       files: rendered.map(({ content: _content, ...metadata }) => metadata),
     },
@@ -173,22 +204,3 @@ function renderInstructionFile(
 function isRendered(value: RenderedInstructionFile | null): value is RenderedInstructionFile {
   return value !== null;
 }
-
-/** Insert instruction markdown after the opening title/summary block of a brief. */
-export function insertInstructionsNearTop(content: string, instructionsMarkdown: string): string {
-  const lines = content.split("\n");
-  const insertAt = findFirstSectionIndexAfterTitle(lines);
-  const before = lines.slice(0, insertAt).join("\n").trimEnd();
-  const after = lines.slice(insertAt).join("\n").trimStart();
-
-  if (!before) return `${instructionsMarkdown}\n\n${after}`.trimEnd();
-  if (!after) return `${before}\n\n${instructionsMarkdown}`.trimEnd();
-  return `${before}\n\n${instructionsMarkdown}\n\n${after}`.trimEnd();
-}
-
-function findFirstSectionIndexAfterTitle(lines: string[]): number {
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].startsWith("## ")) return i;
-  }
-  return lines.length;
-}

package/src/analysis/provider.ts

@@ -14,8 +14,9 @@ import {
   getDefaultWorkspaceRuntime,
   type SemanticProvider,
   type StructuralProvider,
+  unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
-import { getSessionLspService, type SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import { getWorkspaceLspRuntime, type WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
 
 /**
  * Unified code analysis provider combining semantic (LSP-backed) and
@@ -25,7 +26,7 @@ export interface CodeProvider extends SemanticProvider, StructuralProvider {}
 
 /** Availability state for the code provider in a workspace. */
 export type CodeProviderState =
-  | { kind: "ready"; provider: CodeProvider; lspService: SessionLspServiceState }
+  | { kind: "ready"; provider: CodeProvider; lspRuntime: WorkspaceLspRuntimeState }
   | { kind: "unavailable"; reason: string };
 
 /**
@@ -77,7 +78,7 @@ export function getCodeProviderState(cwd: string): CodeProviderState {
       (hasSemantic ? ws.semantic.provider : null) as SemanticProvider | null,
       (hasStructural ? ws.structural.provider : null) as StructuralProvider | null,
     ),
-    lspService: getSessionLspService(cwd),
+    lspRuntime: getWorkspaceLspRuntime(cwd),
   };
 }
 
@@ -93,6 +94,13 @@ export const getCodeProvider = getCodeProviderState;
  * provider methods are forwarded automatically — no need to update
  * the composite wrapper.
  */
+/** Build a composite facade that deliberately exposes structural evidence only. */
+export function createStructuralCodeProvider(
+  structural: StructuralProvider | null,
+): CodeProvider | null {
+  return structural ? createCompositeProvider(null, structural) : null;
+}
+
 function createCompositeProvider(
   semantic: SemanticProvider | null,
   structural: StructuralProvider | null,
@@ -100,29 +108,40 @@ function createCompositeProvider(
   return {
     // ── Semantic methods ──────────────────────────────────────────────
     async references(...args: Parameters<SemanticProvider["references"]>) {
-      return semantic?.references(...args) ?? null;
+      return (
+        semantic?.references(...args) ?? unavailableCodeQuery("Semantic references unavailable")
+      );
     },
     async implementation(...args: Parameters<SemanticProvider["implementation"]>) {
-      return semantic?.implementation(...args) ?? null;
+      return (
+        semantic?.implementation(...args) ??
+        unavailableCodeQuery("Semantic implementations unavailable")
+      );
     },
     async documentSymbols(...args: Parameters<SemanticProvider["documentSymbols"]>) {
-      return semantic?.documentSymbols(...args) ?? null;
+      return (
+        semantic?.documentSymbols(...args) ??
+        unavailableCodeQuery("Semantic document symbols unavailable")
+      );
     },
     async workspaceSymbols(...args: Parameters<SemanticProvider["workspaceSymbols"]>) {
-      return semantic?.workspaceSymbols(...args) ?? null;
+      return (
+        semantic?.workspaceSymbols(...args) ??
+        unavailableCodeQuery("Semantic workspace symbols unavailable")
+      );
     },
     async hover(...args: Parameters<NonNullable<SemanticProvider["hover"]>>) {
-      return semantic?.hover?.(...args) ?? null;
+      return semantic?.hover?.(...args) ?? unavailableCodeQuery("Semantic hover unavailable");
     },
     async definition(...args: Parameters<NonNullable<SemanticProvider["definition"]>>) {
-      return semantic?.definition?.(...args) ?? null;
+      return (
+        semantic?.definition?.(...args) ?? unavailableCodeQuery("Semantic definition unavailable")
+      );
     },
     async codeActions(...args: Parameters<NonNullable<SemanticProvider["codeActions"]>>) {
       return semantic?.codeActions?.(...args) ?? [];
     },
-    async codeActionTitles(...args: Parameters<NonNullable<SemanticProvider["codeActionTitles"]>>) {
-      return semantic?.codeActionTitles?.(...args) ?? null;
-    },
+
     async rename(...args: Parameters<NonNullable<SemanticProvider["rename"]>>) {
       const result = await semantic?.rename?.(...args);
       return (

package/src/analysis/readiness.ts

@@ -1,9 +1,9 @@
 import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
 import {
-  getSessionLspService,
+  getWorkspaceLspRuntime,
   type SemanticReadinessResult,
-  type SessionLspServiceState,
-  waitForSessionLspService,
+  type WorkspaceLspRuntimeState,
+  waitForWorkspaceLspRuntime,
 } from "@mrclrchtr/supi-lsp/api";
 
 export const DEFAULT_SEMANTIC_STARTUP_TIMEOUT_MS = 15_000;
@@ -24,7 +24,7 @@ export async function ensureSemanticReadiness(
   }
 
   if (workspace.semantic.state.kind === "ready") {
-    return { kind: "ready" };
+    return resolveReadySemanticState(cwd, scope, timeoutMs);
   }
 
   if (workspace.semantic.state.kind !== "pending") {
@@ -59,15 +59,35 @@ export async function ensureSemanticReadiness(
     return { kind: "timeout" };
   }
   return scope.kind === "workspace"
-    ? lspState.service.waitUntilReadyForWorkspace({ timeoutMs: remainingAfterLsp })
-    : lspState.service.waitUntilReadyForFile(scope.file, { timeoutMs: remainingAfterLsp });
+    ? lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs: remainingAfterLsp })
+    : lspState.runtime.waitUntilReadyForFile(scope.file, { timeoutMs: remainingAfterLsp });
+}
+
+function resolveReadySemanticState(
+  cwd: string,
+  scope: SemanticStartupScope,
+  timeoutMs: number,
+): Promise<SemanticReadinessResult> | SemanticReadinessResult {
+  const lspState = getWorkspaceLspRuntime(cwd);
+  if (lspState.kind === "ready") {
+    return scope.kind === "workspace"
+      ? lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs })
+      : lspState.runtime.waitUntilReadyForFile(scope.file, { timeoutMs });
+  }
+  return {
+    kind: "unavailable",
+    reason:
+      lspState.kind === "unavailable"
+        ? lspState.reason
+        : `LSP service is ${lspState.kind} for this workspace.`,
+  };
 }
 
 async function resolveSemanticServiceState(
   cwd: string,
   timeoutMs: number,
-): Promise<SessionLspServiceState> {
-  const initialState = getSessionLspService(cwd);
+): Promise<WorkspaceLspRuntimeState> {
+  const initialState = getWorkspaceLspRuntime(cwd);
   if (initialState.kind !== "pending") return initialState;
-  return waitForSessionLspService(cwd, timeoutMs);
+  return waitForWorkspaceLspRuntime(cwd, timeoutMs);
 }