@mrclrchtr/supi-lsp 11.3.0 → 12.0.0

package/src/provider/refactor-planning.ts

@@ -1,14 +1,28 @@
+import { readFileSync } from "node:fs";
 import * as path from "node:path";
 import type {
   CodePosition,
   CodeRequestControl,
+  DisambiguationCandidate,
+  RefactorActionIdentity,
   RefactorResult,
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { CodeActionTriggerKind } from "vscode-languageserver-types";
-import { codeActionKindsForOperation } from "../config/operation-support.ts";
+import { isCodeActionKindInRange, isCodeActionKindWithin } from "../config/operation-support.ts";
 import type { CodeAction } from "../config/types.ts";
-import type { WorkspaceLspRuntime } from "../session/runtime-registry.ts";
+import { raceRequestControl } from "../session/readiness.ts";
+import type { RoutedCodeActionResponse, WorkspaceLspRuntime } from "../session/runtime-registry.ts";
+import {
+  COMMAND_ONLY_ACTION_REASON,
+  captureCommandAction,
+  captureEligibleActions,
+  commandCandidates,
+  isCommandOnlyAction,
+} from "./refactor-command-capture.ts";
+
+export { COMMAND_ONLY_ACTION_REASON };
+
 import {
   normalizeSemanticEdit,
   type SemanticEditNormalizationContext,
@@ -70,48 +84,135 @@ export function collectCodeActionResults(
   return results;
 }
 
-export async function runFilteredCodeActionRefactor(options: {
+/** Options for one code- or source-action planning request. */
+export interface CodeActionRefactorOptions {
   lsp: WorkspaceLspRuntime;
   file: string;
-  position: CodePosition;
-  operation: "update_imports" | "delete_dead_code";
-  range?: SourceRange;
-  matches: (action: CodeAction) => boolean;
+  range: SourceRange;
+  kind: string;
+  title?: string;
+  /** Operation label used in unavailable reasons. */
+  label: "Code action" | "Source action";
   control?: CodeRequestControl;
-}): Promise<RefactorResult> {
-  const { lsp, file, position, operation, matches } = options;
-  const response = await lsp.codeActions(file, options.range ?? position, options.control, {
-    only: codeActionKindsForOperation(operation),
+}
+
+/**
+ * Plan one code action of the requested kind over a file range.
+ *
+ * `kind` matches itself and its dotted sub-kinds, per the LSP CodeActionKind
+ * hierarchy. Disabled actions never match. `title` narrows matches to one exact
+ * title. Distinct precise plans stay ambiguous. One eligible command-only
+ * action runs once so its pushed edit can be captured; see
+ * `refactor-command-capture.ts`.
+ */
+export async function runCodeActionRefactor(
+  options: CodeActionRefactorOptions,
+): Promise<RefactorResult> {
+  return (await attemptCodeActionRefactor(options)).result;
+}
+
+/** Delays before re-requesting a source action that returned no action of the kind. */
+const SOURCE_ACTION_RETRY_DELAYS_MS = [500, 1000] as const;
+
+/**
+ * Plan a whole-file source action, retrying briefly when a server that
+ * advertises the requested kind returns no action of it.
+ *
+ * typescript-language-server returns no fix-all or unused-code source actions
+ * while diagnostics for a just-opened or just-changed file are pending, and
+ * waits itself about 500 ms in the equivalent quick-fix path.
+ */
+export async function runSourceActionRefactor(
+  options: CodeActionRefactorOptions,
+): Promise<RefactorResult> {
+  let attempt = await attemptCodeActionRefactor(options);
+  for (const delayMs of SOURCE_ACTION_RETRY_DELAYS_MS) {
+    if (!attempt.retryable) break;
+    await raceRequestControl(
+      new Promise((resolve) => setTimeout(resolve, delayMs)),
+      options.control,
+    );
+    attempt = await attemptCodeActionRefactor(options);
+  }
+  return attempt.result;
+}
+
+/**
+ * One planning attempt. `retryable` marks a zero-match response from a server
+ * that advertises the requested kind, so a later request may still return it.
+ */
+async function attemptCodeActionRefactor(
+  options: CodeActionRefactorOptions,
+): Promise<{ result: RefactorResult; retryable: boolean }> {
+  const { lsp, file, range, kind, title, label } = options;
+  const response = await lsp.codeActions(file, range, options.control, {
+    only: [kind],
     triggerKind: CodeActionTriggerKind.Invoked,
   });
-  if (!response || response.reason) {
+  if (!response) {
     return {
-      kind: "unavailable",
-      reason: `Refactor operation "${operation}" is unavailable: ${response?.reason ?? "No code actions are available."}`,
+      result: {
+        kind: "unavailable",
+        reason: `${label} "${kind}" is unavailable: no routed LSP client.`,
+      },
+      retryable: false,
     };
   }
-  const actions = response.value;
-  if (!actions || actions.length === 0) {
-    return {
-      kind: "unavailable",
-      reason: `No code actions are available for refactor operation "${operation}".`,
-    };
+  const roots = [...response.authorizedMutationRoots];
+  const unavailable = (reason: string, retryable = false) => ({
+    result: { kind: "unavailable" as const, reason, authorizedMutationRoots: roots },
+    retryable,
+  });
+  if (response.reason || !response.value) {
+    return unavailable(
+      `${label} "${kind}" is unavailable: ${response.reason ?? "no code actions were returned."}`,
+    );
   }
 
-  const matching = actions.filter(matches);
+  const ofKind = response.value
+    .filter(isTitledCodeAction)
+    .filter(
+      (action) => isCodeActionKindWithin(action.kind, kind) && !Object.hasOwn(action, "disabled"),
+    );
+  if (ofKind.length === 0) {
+    const advertised = advertisedFamilyKinds(response.advertisedKinds, kind);
+    return unavailable(
+      noKindMatchReason(kind, advertised),
+      advertised.kinds.some((candidate) => isCodeActionKindInRange(candidate, kind)),
+    );
+  }
+  const matching = title === undefined ? ofKind : ofKind.filter((action) => action.title === title);
   if (matching.length === 0) {
-    return {
-      kind: "unavailable",
-      reason: `No matching precise code action is available for refactor operation "${operation}".`,
-    };
+    const titles = [...new Set(ofKind.map((action) => `"${action.title}"`))].join(", ");
+    return unavailable(
+      `No "${kind}" code action has the title "${title}". Available titles: ${titles}.`,
+    );
   }
 
-  const context: SemanticEditNormalizationContext = {
+  return { result: await planMatchingActions(options, matching, response), retryable: false };
+}
+
+/** Turn the matching actions into one plan, candidates, or an unavailable reason. */
+async function planMatchingActions(
+  options: CodeActionRefactorOptions,
+  matching: CodeAction[],
+  response: RoutedCodeActionResponse,
+): Promise<RefactorResult> {
+  const { lsp, file, kind } = options;
+  const roots = [...response.authorizedMutationRoots];
+  const unavailable = (reason: string): RefactorResult => ({
+    kind: "unavailable",
+    reason,
+    authorizedMutationRoots: roots,
+  });
+  const plans = collectPrecisePlans(matching, {
     getOpenDocumentVersion: (candidate) => lsp.getOpenDocumentVersion(candidate),
     authorizedMutationRoots: response.authorizedMutationRoots,
-  };
-  const plans = collectPrecisePlans(matching, context);
-  if (plans.precise.length === 1) return plans.precise[0].result;
+  });
+  const [single] = plans.precise;
+  if (plans.precise.length === 1 && single) {
+    return { ...single.result, action: { ...actionIdentity(single.action), provenance: "edit" } };
+  }
   if (plans.precise.length > 1) {
     return {
       kind: "ambiguous",
@@ -120,26 +221,84 @@ export async function runFilteredCodeActionRefactor(options: {
       ),
     };
   }
-  return {
-    kind: "unavailable",
-    reason: plans.unavailableReason
+  if (matching.every(isCommandOnlyAction)) {
+    const eligible = captureEligibleActions(matching, response.advertisedCommands);
+    const [only] = eligible;
+    if (eligible.length === 1 && only) {
+      return captureCommandAction({ lsp, file, action: only, control: options.control });
+    }
+    return eligible.length > 1
+      ? commandCandidates(eligible)
+      : unavailable(COMMAND_ONLY_ACTION_REASON);
+  }
+  return unavailable(
+    plans.unavailableReason
       ? `Matching code action is unavailable: ${plans.unavailableReason}`
-      : `Matching code actions for refactor operation "${operation}" did not produce precise edits.`,
-  };
+      : `Matching "${kind}" code actions did not produce precise edits.`,
+  );
 }
 
-export function isUpdateImportsCodeAction(action: CodeAction): boolean {
-  const kind = typeof action?.kind === "string" ? action.kind : "";
-  return kind === "source.organizeImports" || kind.startsWith("source.organizeImports.");
+/** Compute the zero-based UTF-16 range that covers a file's full current disk text. */
+export function wholeDocumentRange(file: string): SourceRange | null {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf-8");
+  } catch {
+    return null;
+  }
+  const lines = text.split(/\r\n|\r|\n/);
+  return {
+    start: { line: 0, character: 0 },
+    end: { line: lines.length - 1, character: lines.at(-1)?.length ?? 0 },
+  };
 }
 
-export function isDeleteDeadCodeCodeAction(action: CodeAction): boolean {
-  const kind = typeof action?.kind === "string" ? action.kind : "";
-  return codeActionKindsForOperation("delete_dead_code").some(
-    (requested) => kind === requested || kind.startsWith(`${requested}.`),
+function isTitledCodeAction(value: unknown): value is CodeAction {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { title?: unknown }).title === "string"
   );
 }
 
+/** Advertised kinds in one CodeActionKind family, such as `source*`. */
+interface AdvertisedFamilyKinds {
+  /** Listed non-empty kinds in the requested kind's top-level family. */
+  readonly kinds: readonly string[];
+  /** The server lists CodeActionKind.Empty or no kinds, so it may return any kind. */
+  readonly anyKind: boolean;
+}
+
+function advertisedFamilyKinds(
+  advertised: readonly string[] | undefined,
+  kind: string,
+): AdvertisedFamilyKinds {
+  const family = kind.split(".")[0] ?? kind;
+  return {
+    kinds: (advertised ?? []).filter(
+      (candidate) => candidate !== "" && isCodeActionKindWithin(candidate, family),
+    ),
+    anyKind: !advertised || advertised.includes(""),
+  };
+}
+
+function noKindMatchReason(kind: string, advertised: AdvertisedFamilyKinds): string {
+  const parts = [`No code action matches kind "${kind}" here.`];
+  if (advertised.kinds.length > 0) {
+    parts.push(`Server-advertised kinds: ${advertised.kinds.join(", ")}.`);
+  }
+  if (advertised.anyKind) {
+    parts.push("The server may return any code-action kind but returned none of this kind.");
+  } else if (advertised.kinds.length === 0) {
+    parts.push("The server advertises no kinds in this family.");
+  }
+  return parts.join(" ");
+}
+
+function actionIdentity(action: CodeAction): RefactorActionIdentity {
+  return { kind: typeof action.kind === "string" ? action.kind : "", title: action.title };
+}
+
 interface PreciseCodeActionPlan {
   action: CodeAction;
   result: Extract<RefactorResult, { kind: "precise" }>;
@@ -187,18 +346,14 @@ function refactorCandidate(
   result: Extract<RefactorResult, { kind: "precise" }>,
   index: number,
   plans: readonly { action: CodeAction }[],
-): {
-  description: string;
-  file?: string;
-  line?: number;
-  character?: number;
-} {
+): DisambiguationCandidate {
   const firstEdit = result.edits.edits[0];
   const sameTitleCount = plans.filter((plan) => plan.action.title === action.title).length;
   const description =
     sameTitleCount > 1 ? `${action.title} (alternative ${index + 1})` : action.title;
   return {
     description,
+    ...actionIdentity(action),
     ...(firstEdit
       ? {
           file: firstEdit.file,

package/src/provider/semantic-symbol-mapper.ts

@@ -2,10 +2,11 @@ import { readFile } from "node:fs/promises";
 import type {
   CodeLocation,
   CodeSymbol,
-  DeclarationNesting,
+  DeclarationLevel,
   DocumentCodeSymbol,
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { childDeclarationLevel } from "@mrclrchtr/supi-code-runtime/api";
 import { uriToFile } from "@mrclrchtr/supi-core/path";
 import type {
   DocumentSymbol,
@@ -100,15 +101,26 @@ export async function mapDocumentSymbols(
 ): Promise<DocumentCodeSymbol[]> {
   return flattenDocumentSymbols(symbols, filePath, null, {
     sourceLines: await readSourceLines(filePath),
-    nesting: "top-level",
+    parent: null,
   });
 }
 
+/** Level of a symbol reported inside `parent`, or top-level without one. */
+function levelWithin(
+  parent: { readonly kind: string; readonly level: DeclarationLevel } | null,
+  kind: string,
+): DeclarationLevel {
+  return parent ? childDeclarationLevel(parent, kind) : "top-level";
+}
+
 function flattenDocumentSymbols(
   symbols: DocumentSymbol[] | SymbolInformation[],
   filePath: string,
   container: string | null,
-  context: { sourceLines: readonly string[] | null; nesting: DeclarationNesting },
+  context: {
+    sourceLines: readonly string[] | null;
+    parent: { readonly kind: string; readonly level: DeclarationLevel } | null;
+  },
 ): DocumentCodeSymbol[] {
   const result: DocumentCodeSymbol[] = [];
   for (const sym of symbols) {
@@ -116,15 +128,13 @@ function flattenDocumentSymbols(
     let document: DocumentSymbol | null = null;
     if (isSymbolInformation(sym)) information = sym;
     else document = sym;
+    const kind = symbolKindName(sym.kind);
+    const level = information ? "unknown" : levelWithin(context.parent, kind);
+    const childContext = { sourceLines: context.sourceLines, parent: { kind, level } };
     const declarationRange = toValidRange(document?.range ?? information?.location.range);
     if (!declarationRange) {
       if (document?.children?.length) {
-        result.push(
-          ...flattenDocumentSymbols(document.children, filePath, sym.name, {
-            sourceLines: context.sourceLines,
-            nesting: "nested",
-          }),
-        );
+        result.push(...flattenDocumentSymbols(document.children, filePath, sym.name, childContext));
       }
       continue;
     }
@@ -134,23 +144,18 @@ function flattenDocumentSymbols(
       : null;
     const symbol: DocumentCodeSymbol = {
       name: sym.name,
-      kind: symbolKindName(sym.kind),
+      kind,
       file: filePath,
       declarationAnchor: { line: declStart.line + 1, character: declStart.character + 1 },
       container: information?.containerName ?? container,
-      nesting: information ? "unknown" : context.nesting,
+      level,
     };
     if (nameStart) {
       symbol.nameAnchor = { line: nameStart.line + 1, character: nameStart.character + 1 };
     }
     result.push(symbol);
     if (document?.children?.length) {
-      result.push(
-        ...flattenDocumentSymbols(document.children, filePath, sym.name, {
-          sourceLines: context.sourceLines,
-          nesting: "nested",
-        }),
-      );
+      result.push(...flattenDocumentSymbols(document.children, filePath, sym.name, childContext));
     }
   }
   return result;

package/src/session/route-boundary.ts

@@ -0,0 +1,26 @@
+/** Project-root boundary for mutation requests on one routed client. */
+
+import { realpathSync } from "node:fs";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+
+/**
+ * Return why a file cannot be refactored by the client routed to it, or null.
+ *
+ * A file without its own project markers routes to a server rooted at the
+ * session directory. Its edits would fail the apply-time root check, so refuse
+ * before the request. Real paths are compared, so a link inside the root
+ * cannot reach an outside file.
+ */
+export function outsideRouteRootReason(file: string, root: string): string | null {
+  return isWithinOrEqual(canonical(root), canonical(file))
+    ? null
+    : `File ${file} is outside the language server's project root ${root}.`;
+}
+
+function canonical(file: string): string {
+  try {
+    return realpathSync(file);
+  } catch {
+    return file;
+  }
+}

package/src/session/runtime-registry.ts

@@ -1,11 +1,13 @@
 // Shared session-scoped LSP service registry reused by peer extensions.
 
 // biome-ignore lint/style/noExcessiveLinesPerFile: session registry, runtime recovery, and telemetry stay in one file; splitting would hide the recovery contract.
+import { fileURLToPath } from "node:url";
 import {
   type CodeQueryResult,
   type CodeRequestControl,
   isCodeRequestInterruption,
   mapCodeQueryResult,
+  partialCodeQuery,
   throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
@@ -16,6 +18,8 @@ import {
 import { resolveToolPath as resolveSessionPath } from "@mrclrchtr/supi-core/path";
 import { createSessionStateRegistry } from "@mrclrchtr/supi-core/session";
 import { CodeActionTriggerKind } from "vscode-languageserver-types";
+import type { CommandEditCaptureResult } from "../client/client-edit-capture.ts";
+import { advertisedCodeActionKinds } from "../config/operation-support.ts";
 import type {
   CodeAction,
   Diagnostic,
@@ -37,7 +41,12 @@ import type {
   WorkspaceSentinelSyncResult,
 } from "../diagnostics/workspace-sentinels.ts";
 import type { LspManager } from "../manager/manager.ts";
+import {
+  COMMAND_ONLY_ACTION_REASON,
+  captureEligibleActions,
+} from "../provider/refactor-command-capture.ts";
 import { raceReadinessValue } from "./readiness.ts";
+import { outsideRouteRootReason } from "./route-boundary.ts";
 import type {
   DiagnosticEvidenceSummary,
   ProcessCrashRecoveryReport,
@@ -47,6 +56,7 @@ import type {
 import { runRoutedRename } from "./runtime-rename.ts";
 import type {
   BulkTrackFilesResult,
+  RoutedCodeActionResponse,
   RoutedMutationResponse,
   SemanticReadinessResult,
   WorkspaceCodeActionRequestOptions,
@@ -54,6 +64,9 @@ import type {
   WorkspaceLspRuntimeState,
 } from "./workspace-lsp-runtime.ts";
 
+/** Upper bound for a server command run to capture its pushed edit. */
+const COMMAND_CAPTURE_TIMEOUT_MS = 10_000;
+
 export type {
   ProcessCrashDiagnosticDemand,
   WorkspaceLspDiagnosticSurface,
@@ -82,6 +95,7 @@ export {
 export type {
   BulkTrackFileOutcome,
   BulkTrackFilesResult,
+  RoutedCodeActionResponse,
   RoutedMutationDocumentSnapshot,
   RoutedMutationResponse,
   SemanticReadinessResult,
@@ -193,9 +207,14 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       control,
     });
     if (!client) return unavailableFileQuery("references", resolvedPath);
-    return mapCodeQueryResult(
-      await client.references(resolvedPath, position, control),
-      (data) => data ?? [],
+    return this.withProjectCoverage(
+      client,
+      { file: resolvedPath, position },
+      "references",
+      mapCodeQueryResult(
+        await client.references(resolvedPath, position, control),
+        (data) => data ?? [],
+      ),
     );
   }
 
@@ -211,7 +230,30 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       control,
     });
     if (!client) return unavailableFileQuery("implementation", resolvedPath);
-    return client.implementation(resolvedPath, position, control);
+    return this.withProjectCoverage(
+      client,
+      { file: resolvedPath, position },
+      "implementation",
+      await client.implementation(resolvedPath, position, control),
+    );
+  }
+
+  /**
+   * Downgrade a completed project-wide answer to partial when the TypeScript
+   * server may not have searched every relevant project.
+   */
+  private withProjectCoverage<T extends Location[] | Location | LocationLink[] | null>(
+    client: NonNullable<Awaited<ReturnType<LspManager["ensureFileOpen"]>>>,
+    target: { readonly file: string; readonly position: Position },
+    request: "references" | "implementation",
+    result: CodeQueryResult<T>,
+  ): CodeQueryResult<T> {
+    if (result.kind !== "completed") return result;
+    const gap = this.manager.typeScriptProjectCoverageGap(client, target.file, request, {
+      resultFiles: locationFiles(result.data),
+      position: target.position,
+    });
+    return gap ? partialCodeQuery(result.data, gap) : result;
   }
 
   async documentSymbols(
@@ -258,12 +300,39 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     return this.manager.getOpenDocumentVersion(this.resolveFilePath(filePath));
   }
 
+  async captureCodeActionEdit(
+    filePath: string,
+    action: CodeAction,
+    control?: CodeRequestControl,
+  ): Promise<RoutedMutationResponse<CommandEditCaptureResult | null> | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    const client = await this.manager.ensureFileOpen(resolvedPath, {
+      recoverProcessCrash: true,
+      protectInputs: true,
+      control,
+    });
+    if (!client) return null;
+    const authorizedMutationRoots = [client.root];
+    const outside = outsideRouteRootReason(resolvedPath, client.root);
+    if (outside) return { value: null, authorizedMutationRoots, reason: outside };
+    const listed = client.serverCapabilities?.executeCommandProvider?.commands;
+    const [eligible] = captureEligibleActions([action], Array.isArray(listed) ? listed : undefined);
+    if (!eligible) {
+      return { value: null, authorizedMutationRoots, reason: COMMAND_ONLY_ACTION_REASON };
+    }
+    const value = await client.captureCommandEdits(eligible.command, {
+      timeoutMs: COMMAND_CAPTURE_TIMEOUT_MS,
+      ...(control ? { control } : {}),
+    });
+    return { value, authorizedMutationRoots };
+  }
+
   async codeActions(
     filePath: string,
     positionOrRange: Position | Range,
     control?: CodeRequestControl,
     options?: WorkspaceCodeActionRequestOptions,
-  ): Promise<RoutedMutationResponse<CodeAction[] | null> | null> {
+  ): Promise<RoutedCodeActionResponse | null> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
@@ -271,6 +340,10 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       control,
     });
     if (!client) return null;
+    const outside = outsideRouteRootReason(resolvedPath, client.root);
+    if (outside) {
+      return { value: null, authorizedMutationRoots: [client.root], reason: outside };
+    }
 
     const range = isRange(positionOrRange)
       ? positionOrRange
@@ -285,21 +358,23 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       triggerKind: options?.triggerKind ?? CodeActionTriggerKind.Invoked,
       ...(options?.only ? { only: [...options.only] } : {}),
     };
+    const advertisedKinds = advertisedCodeActionKinds(client.serverCapabilities ?? null);
+    const advertisedCommands = client.serverCapabilities?.executeCommandProvider?.commands;
+    const routed = {
+      authorizedMutationRoots: [client.root],
+      ...(advertisedKinds ? { advertisedKinds } : {}),
+      ...(Array.isArray(advertisedCommands) ? { advertisedCommands } : {}),
+    };
     if (typeof client.codeActionsDetailed === "function") {
       const result = await client.codeActionsDetailed(resolvedPath, range, context, control);
-      return {
-        value: result.kind === "completed" ? result.data : null,
-        authorizedMutationRoots: [client.root],
-        ...(result.kind === "unavailable"
-          ? { reason: result.reason }
-          : result.data === null
-            ? { reason: "LSP server returned no code actions." }
-            : {}),
-      };
+      // A completed `null` result means the server has no actions here (LSP spec).
+      return result.kind === "completed"
+        ? { ...routed, value: result.data ?? [] }
+        : { ...routed, value: null, reason: result.reason };
     }
     return {
-      value: await client.codeActions(resolvedPath, range, context, control),
-      authorizedMutationRoots: [client.root],
+      ...routed,
+      value: (await client.codeActions(resolvedPath, range, context, control)) ?? [],
     };
   }
 
@@ -605,6 +680,21 @@ export async function waitForWorkspaceLspRuntime(
   return state;
 }
 
+/** Local file paths of LSP locations or location links; non-file URIs are skipped. */
+function locationFiles(data: Location[] | Location | LocationLink[] | null): string[] {
+  const items: (Location | LocationLink)[] =
+    data === null ? [] : Array.isArray(data) ? data : [data];
+  return items.flatMap((item) => {
+    const uri = "targetUri" in item ? item.targetUri : item.uri;
+    if (!uri.startsWith("file:")) return [];
+    try {
+      return [fileURLToPath(uri)];
+    } catch {
+      return [];
+    }
+  });
+}
+
 /** Remove the LSP service state for a session cwd. */
 export function clearWorkspaceLspRuntime(cwd: string): void {
   registry.clear(cwd);

package/src/session/runtime-rename.ts

@@ -5,6 +5,7 @@ import type { SemanticInputDocumentSnapshot } from "../client/client-semantic-in
 import type { Position, WorkspaceEdit } from "../config/types.ts";
 import type { LspManager } from "../manager/manager.ts";
 import { discoverSemanticEditFiles } from "../provider/semantic-edit-discovery.ts";
+import { outsideRouteRootReason } from "./route-boundary.ts";
 import type {
   RoutedMutationDocumentSnapshot,
   RoutedMutationResponse,
@@ -26,6 +27,8 @@ export async function runRoutedRename(options: {
   });
   if (!client) return null;
   const authorizedMutationRoots = [client.root];
+  const outside = outsideRouteRootReason(file, client.root);
+  if (outside) return { value: null, authorizedMutationRoots, reason: outside };
 
   if (typeof client.renameDetailedWithSnapshots === "function") {
     return renameWithSnapshots({