@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/session/inspect/collect.ts

@@ -2,6 +2,8 @@
 
 import {
   type CodePosition,
+  type CodeRequestControl,
+  isCodeRequestInterruption,
   mapCodeQueryResult,
   type OutlineData,
   type SemanticProvider,
@@ -27,6 +29,7 @@ export interface InspectCollectionInput {
   readonly line: number;
   readonly character: number;
   readonly lineCount: number;
+  readonly requestControl?: CodeRequestControl;
   readonly structural: StructuralProvider | null;
   readonly semantic: SemanticProvider | null;
   readonly semanticUnavailableReason: string;
@@ -50,7 +53,12 @@ async function collectNode(
 ): Promise<InspectObservation<InspectNode | null>> {
   if (!input.structural) return unavailableCodeQuery("No structural node provider is active.");
   try {
-    const result = await input.structural.nodeAt(input.file, input.line, input.character);
+    const result = await input.structural.nodeAt(
+      input.file,
+      input.line,
+      input.character,
+      input.requestControl,
+    );
     if (result.kind !== "success") return unavailableCodeQuery(result.message);
     return {
       kind: "completed",
@@ -65,6 +73,7 @@ async function collectNode(
       },
     };
   } catch (error) {
+    if (isCodeRequestInterruption(error, input.requestControl)) throw error;
     return unavailableCodeQuery(failureReason("Structural node lookup", error));
   }
 }
@@ -74,7 +83,7 @@ async function collectEnclosingSymbol(
 ): Promise<InspectObservation<InspectEnclosingSymbol | null>> {
   if (!input.structural) return unavailableCodeQuery("No structural outline provider is active.");
   try {
-    const result = await input.structural.outline(input.file);
+    const result = await input.structural.outline(input.file, input.requestControl);
     if (result.kind !== "success") return unavailableCodeQuery(result.message);
     return {
       kind: "completed",
@@ -84,6 +93,7 @@ async function collectEnclosingSymbol(
       }),
     };
   } catch (error) {
+    if (isCodeRequestInterruption(error, input.requestControl)) throw error;
     return unavailableCodeQuery(failureReason("Structural outline lookup", error));
   }
 }
@@ -98,6 +108,7 @@ async function collectHover(
       (hover) => hover?.contents ?? null,
     );
   } catch (error) {
+    if (isCodeRequestInterruption(error, input.requestControl)) throw error;
     return unavailableCodeQuery(failureReason("Hover lookup", error));
   }
 }
@@ -131,6 +142,7 @@ async function collectDefinition(
       ? { kind: "partial", data: definitions, reason: reasons.join(" ") }
       : { kind: "completed", data: definitions };
   } catch (error) {
+    if (isCodeRequestInterruption(error, input.requestControl)) throw error;
     return unavailableCodeQuery(failureReason("Definition lookup", error));
   }
 }
@@ -142,7 +154,11 @@ async function collectDiagnostics(
     return unavailableCodeQuery(lspUnavailableReason(input.lspState));
   }
   try {
-    const result = await input.lspState.runtime.fileDiagnostics(input.file, 4);
+    const result = await input.lspState.runtime.fileDiagnostics(
+      input.file,
+      4,
+      input.requestControl,
+    );
     if (result.kind === "unavailable") return result;
     const diagnostics = result.data
       .filter((diagnostic) => diagnosticOverlapsWindow(diagnostic.range, input))
@@ -159,6 +175,7 @@ async function collectDiagnostics(
       ? { kind: "partial", data: diagnostics, reason: result.reason }
       : { kind: "completed", data: diagnostics };
   } catch (error) {
+    if (isCodeRequestInterruption(error, input.requestControl)) throw error;
     return unavailableCodeQuery(failureReason("Diagnostic lookup", error));
   }
 }

package/src/session/inspect-workflow.ts

@@ -1,6 +1,8 @@
 /** Session-owned point inspection workflow. */
 
 import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
+import { withSemanticRequestControl } from "../analysis/provider.ts";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import type { CapabilityAdapter, ReadinessOutcome } from "./capability-adapter.ts";
 import { parseInspectWorkflowInput } from "./input/workflows.ts";
 import { collectInspectSections } from "./inspect/collect.ts";
@@ -37,14 +39,17 @@ export async function runInspectWorkflow(
     phase: "providers",
     message: "Collecting point facts",
   });
-  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
-    kind: "file",
-    file: point.value.file,
-  });
+  const readiness = await deps.capability.ensureSemanticReadiness(
+    deps.cwd,
+    { kind: "file", file: point.value.file },
+    control,
+  );
   throwIfAborted(control);
 
   const semanticReady = readiness.kind === "ready";
-  const semantic = semanticReady ? deps.capability.getSemanticProvider(deps.cwd) : null;
+  const semantic = semanticReady
+    ? withSemanticRequestControl(deps.capability.getSemanticProvider(deps.cwd), control)
+    : null;
   const lspState = semanticReady
     ? deps.capability.getLspRuntimeState(deps.cwd)
     : unavailableLspState(readiness);
@@ -54,6 +59,7 @@ export async function runInspectWorkflow(
     line: point.value.line,
     character: point.value.character,
     lineCount: point.value.lineCount,
+    requestControl: control,
     structural: deps.capability.getStructuralProvider(deps.cwd),
     semantic,
     semanticUnavailableReason: semantic
@@ -150,7 +156,7 @@ function semanticReadinessReason(readiness: ReadinessOutcome): string {
     case "ready":
       return "No semantic provider is active for this file.";
     case "timeout":
-      return "Semantic readiness timed out.";
+      return SEMANTIC_READINESS_TIMEOUT_REASON;
     case "unavailable":
       return readiness.reason;
   }

package/src/session/orientation/collect.ts

@@ -2,6 +2,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import { isCodeRequestInterruption } from "@mrclrchtr/supi-code-runtime/api";
 import { uriToFile } from "@mrclrchtr/supi-core/path";
 import type { Diagnostic } from "@mrclrchtr/supi-lsp/api";
 import {
@@ -69,6 +70,7 @@ async function executeOrientationContext(
     focus: input.focus,
     maxResults: input.maxResults ?? 10,
     lspRuntime: deps.lspRuntime,
+    requestControl: deps.requestControl,
   });
 }
 
@@ -181,7 +183,7 @@ async function buildEnrichedDefsSection(
       hasStructuralEvidence,
       hasSemanticEvidence: contextHasSemanticEvidence,
       status: contextHasSemanticEvidence ? "partial" : "unavailable",
-      reason: "Definition targets require a live language server.",
+      reason: deps.semanticReadinessReason ?? "Definition targets require a live language server.",
       evidenceLists: [],
     };
   }
@@ -262,6 +264,7 @@ async function collectDefinitionTargets(
       evidenceLists: [evidence.metadata],
     };
   } catch (error) {
+    if (isCodeRequestInterruption(error, deps.requestControl)) throw error;
     return {
       items: [],
       hasSemanticEvidence: false,
@@ -289,13 +292,17 @@ async function buildDiagnosticsSection(
         },
       ],
       false,
-      "Diagnostics require a live language server.",
+      deps.semanticReadinessReason ?? "Diagnostics require a live language server.",
     );
   }
 
   try {
     const targetFile = path.resolve(deps.cwd, target.file);
-    const result = await deps.lspRuntime.runtime.fileDiagnostics(targetFile, 4);
+    const result = await deps.lspRuntime.runtime.fileDiagnostics(
+      targetFile,
+      4,
+      deps.requestControl,
+    );
     if (result.kind === "unavailable") {
       return unavailableTargetSection(
         [{ kind: "paragraph", text: `Diagnostics unavailable for this target — ${result.reason}` }],
@@ -331,6 +338,7 @@ async function buildDiagnosticsSection(
       evidenceLists: [evidence.metadata],
     };
   } catch (error) {
+    if (isCodeRequestInterruption(error, deps.requestControl)) throw error;
     return unavailableTargetSection(
       [{ kind: "paragraph", text: "Diagnostics failed to load." }],
       false,
@@ -492,6 +500,7 @@ async function maybeGatherTreeContext(
     target.displayLine,
     target.displayCharacter,
     target.anchorKind !== "declaration",
+    deps.requestControl,
   );
 }
 

package/src/session/orientation/context-facts.ts

@@ -1,5 +1,6 @@
 import { statSync } from "node:fs";
 import * as path from "node:path";
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
 import type {
   ArchitectureModel,
@@ -32,6 +33,7 @@ interface ContextFactsInput {
   readonly maxResults: number;
   readonly provider: CodeProvider | null;
   readonly lspRuntime: WorkspaceLspRuntimeState;
+  readonly requestControl?: CodeRequestControl;
 }
 
 /** Collect direct filesystem, parsed-manifest, and explicit-provider Orientation facts. */
@@ -115,7 +117,7 @@ async function collectFileFacts(
   });
   appendTopologyWarning(builder, input.model);
   appendPackageContext(builder, input.model, focus);
-  await appendStructuralFileFacts(builder, input.provider, focus);
+  await appendStructuralFileFacts(builder, input.provider, focus, input.requestControl);
   appendPrioritySignals(builder, {
     scope: focus,
     isFile: true,

package/src/session/orientation/context-sections.ts

@@ -1,6 +1,11 @@
 import { readdirSync } from "node:fs";
 import * as path from "node:path";
-import type { CodeResult, ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type CodeRequestControl,
+  type CodeResult,
+  type ConfidenceMode,
+  isCodeRequestInterruption,
+} from "@mrclrchtr/supi-code-runtime/api";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
 import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
 import type { EvidenceListMetadata, EvidencePartialReason } from "../../analysis/evidence.ts";
@@ -153,6 +158,7 @@ export async function appendStructuralFileFacts(
   builder: ContextOrientationBuilder,
   provider: CodeProvider | null,
   file: string,
+  requestControl?: CodeRequestControl,
 ): Promise<void> {
   if (!provider) {
     appendUnavailableStructuralSections(builder);
@@ -162,19 +168,22 @@ export async function appendStructuralFileFacts(
   await appendStructuralList(builder, {
     key: "structural.outline",
     title: "Provider outline",
-    collect: () => provider.outline(file),
+    collect: () => provider.outline(file, requestControl),
+    requestControl,
     render: (item) => `\`${item.name}\` (${item.kind}, L${item.startLine}–L${item.endLine})`,
   });
   await appendStructuralList(builder, {
     key: "structural.imports",
     title: "Provider imports",
-    collect: () => provider.imports(file),
+    collect: () => provider.imports(file, requestControl),
+    requestControl,
     render: (item) => `\`${item.moduleSpecifier}\``,
   });
   await appendStructuralList(builder, {
     key: "structural.exports",
     title: "Provider exports",
-    collect: () => provider.exports(file),
+    collect: () => provider.exports(file, requestControl),
+    requestControl,
     render: (item) => `\`${item.name}\` (${item.kind})`,
   });
 }
@@ -201,12 +210,14 @@ async function appendStructuralList<T>(
     title: string;
     collect: () => Promise<CodeResult<T[]>>;
     render: (item: T) => string;
+    requestControl?: CodeRequestControl;
   },
 ): Promise<void> {
   let result: CodeResult<T[]>;
   try {
     result = await input.collect();
   } catch (error) {
+    if (isCodeRequestInterruption(error, input.requestControl)) throw error;
     appendUnavailable(builder, {
       key: input.key,
       title: input.title,
@@ -246,7 +257,8 @@ export function appendPrioritySignals(
 ): void {
   if (input.lspRuntime.kind !== "ready") return;
   const scopePath = path.resolve(input.scope);
-  const entries = input.lspRuntime.runtime.getOutstandingDiagnosticSummary(2).filter((entry) => {
+  const snapshot = input.lspRuntime.runtime.getOutstandingDiagnosticSummary(2);
+  const entries = snapshot.entries.filter((entry) => {
     const file = path.resolve(input.cwd, entry.file);
     return input.isFile ? file === scopePath : isWithinOrEqual(scopePath, file);
   });
@@ -265,8 +277,9 @@ export function appendPrioritySignals(
     confidence: "semantic",
     provenance: [{ source: "semantic", capability: "LSP diagnostic snapshot" }],
     status: "partial",
-    reason:
-      "This is the current LSP snapshot, not a complete diagnostic scan; use code_health for diagnostic status.",
+    reason: snapshot.current
+      ? "This is the current LSP snapshot, not a complete diagnostic scan; use code_health for diagnostic status."
+      : "This LSP snapshot was invalidated by a document or workspace change; use code_health with refresh:true before relying on it.",
   });
 }
 

package/src/session/orientation/gather.ts

@@ -6,10 +6,12 @@
  * evidence collector in `collect.ts`.
  */
 
-import type {
-  SemanticProvider,
-  SourceRange,
-  StructuralProvider,
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+  type SemanticProvider,
+  type SourceRange,
+  type StructuralProvider,
 } from "@mrclrchtr/supi-code-runtime/api";
 
 /** Structural provider subset plus optional semantic hover/definition used for gathering. */
@@ -64,6 +66,7 @@ export async function gatherSubstrateContext(
   line: number,
   character: number,
   positionStrict: boolean,
+  requestControl?: CodeRequestControl,
 ): Promise<SubstrateContext> {
   let nodeInfo: SubstrateContext["nodeInfo"] = null;
   let outline: SubstrateContext["outline"] = [];
@@ -76,7 +79,7 @@ export async function gatherSubstrateContext(
 
   try {
     if (positionStrict) {
-      const nodeResult = await provider.nodeAt(relPath, line, character);
+      const nodeResult = await provider.nodeAt(relPath, line, character, requestControl);
       if (nodeResult.kind === "success") {
         nodeInfo = {
           type: nodeResult.data.type,
@@ -88,7 +91,7 @@ export async function gatherSubstrateContext(
       }
     }
 
-    const outlineResult = await provider.outline(relPath);
+    const outlineResult = await provider.outline(relPath, requestControl);
     if (outlineResult.kind === "success") {
       outline = outlineResult.data.map((item) => ({
         name: item.name,
@@ -98,12 +101,12 @@ export async function gatherSubstrateContext(
       }));
     }
 
-    const importsResult = await provider.imports(relPath);
+    const importsResult = await provider.imports(relPath, requestControl);
     if (importsResult.kind === "success") {
       imports = importsResult.data;
     }
 
-    const exportsResult = await provider.exports(relPath);
+    const exportsResult = await provider.exports(relPath, requestControl);
     if (exportsResult.kind === "success") {
       exports = exportsResult.data.map((item) => ({
         name: item.name,
@@ -119,7 +122,8 @@ export async function gatherSubstrateContext(
           character: character - 1,
         });
         if (hoverResult.kind !== "unavailable" && hoverResult.data) hover = hoverResult.data;
-      } catch {
+      } catch (error) {
+        if (isCodeRequestInterruption(error, requestControl)) throw error;
         // hover failed — continue without it
       }
     }
@@ -137,11 +141,13 @@ export async function gatherSubstrateContext(
             range: loc.range,
           }));
         }
-      } catch {
+      } catch (error) {
+        if (isCodeRequestInterruption(error, requestControl)) throw error;
         // definition failed — continue without it
       }
     }
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, requestControl)) throw error;
     // Provider not available
   }
 

package/src/session/orientation-types.ts

@@ -1,4 +1,4 @@
-import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { CodeRequestControl, ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
 import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
 import type { ArchitectureModel } from "../analysis/architecture/model.ts";
 import type { EvidenceListMetadata } from "../analysis/evidence.ts";
@@ -37,6 +37,9 @@ export interface OrientationDeps {
   readonly provider: CodeProvider | null;
   readonly cwd: string;
   readonly lspRuntime: WorkspaceLspRuntimeState;
+  /** Typed reason to surface when target semantic readiness timed out. */
+  readonly semanticReadinessReason?: string;
+  readonly requestControl?: CodeRequestControl;
 }
 
 /**

package/src/session/orientation-workflow.ts

@@ -8,7 +8,8 @@ import {
   collectInstructionFiles,
   findInstructionFilesForDirectory,
 } from "../analysis/instruction-files.ts";
-import { createStructuralCodeProvider } from "../analysis/provider.ts";
+import { createStructuralCodeProvider, withSemanticRequestControl } from "../analysis/provider.ts";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import { normalizePath } from "../analysis/search/paths.ts";
 import { loadCodeIntelligenceConfig } from "../config.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
@@ -33,6 +34,8 @@ export interface OrientationWorkflowDeps extends TargetWorkflowDeps {
   readonly markInstructionDirsSurfaced: (directories: string[]) => void;
   /** Whether the project is trusted — controls instruction-file discovery. */
   readonly projectTrusted: boolean;
+  /** Global config home for hermetic config reads; undefined uses os.homedir(). */
+  readonly homeDir?: string;
 }
 
 /** Resolve the Orientation focus and collect immutable facts for presentation adapters. */
@@ -58,8 +61,9 @@ export async function runOrientationWorkflow(
   if (!request.focus) {
     const result = await executeOrientation(
       { maxResults },
-      { model, provider, lspRuntime, cwd: deps.cwd },
+      { model, provider, lspRuntime, cwd: deps.cwd, requestControl: control },
     );
+    throwIfAborted(control);
     return { kind: "completed", data: result };
   }
 
@@ -74,8 +78,9 @@ export async function runOrientationWorkflow(
       focus: focus.path,
       maxResults,
     },
-    { model, provider, lspRuntime, cwd: deps.cwd },
+    { model, provider, lspRuntime, cwd: deps.cwd, requestControl: control },
   );
+  throwIfAborted(control);
   const withInstructions = addInstructionFiles(result, focus.path, deps);
   return { kind: "completed", data: withInstructions };
 }
@@ -101,7 +106,9 @@ async function orientTarget(options: {
       maxResults,
     },
     deps,
+    control,
   );
+  throwIfAborted(control);
   if (target.kind === "target-group") {
     return {
       kind: "invalid-input",
@@ -133,19 +140,22 @@ async function orientTarget(options: {
   throwIfAborted(control);
 
   const entry = target.entry;
-  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
-    kind: "file",
-    file: entry.file,
-  });
+  const readiness = await deps.capability.ensureSemanticReadiness(
+    deps.cwd,
+    { kind: "file", file: entry.file },
+    control,
+  );
   const semanticReady = readiness.kind === "ready";
   const provider = semanticReady
-    ? deps.capability.getProvider(deps.cwd)
+    ? withSemanticRequestControl(deps.capability.getProvider(deps.cwd), control)
     : createStructuralCodeProvider(deps.capability.getStructuralProvider(deps.cwd));
+  const semanticReadinessReason =
+    readiness.kind === "timeout" ? SEMANTIC_READINESS_TIMEOUT_REASON : undefined;
   const lspRuntime = semanticReady
     ? deps.capability.getLspRuntimeState(deps.cwd)
     : {
         kind: "unavailable" as const,
-        reason: readiness.kind === "timeout" ? "Semantic readiness timed out" : readiness.reason,
+        reason: readiness.kind === "timeout" ? SEMANTIC_READINESS_TIMEOUT_REASON : readiness.reason,
       };
   const result = await executeOrientation(
     { target: entry, maxResults },
@@ -153,9 +163,12 @@ async function orientTarget(options: {
       model,
       provider,
       lspRuntime,
+      semanticReadinessReason,
       cwd: deps.cwd,
+      requestControl: control,
     },
   );
+  throwIfAborted(control);
   return {
     kind: "completed",
     data: addTargetSummary(result, entry, target.notes, deps.cwd),
@@ -194,7 +207,7 @@ function addInstructionFiles(
   deps: OrientationWorkflowDeps,
 ): Awaited<ReturnType<typeof executeOrientation>> {
   if (!deps.projectTrusted || !isDirectory(focusPath)) return result;
-  const config = loadCodeIntelligenceConfig(deps.cwd);
+  const config = loadCodeIntelligenceConfig(deps.cwd, deps.homeDir);
   const matches = findInstructionFilesForDirectory({
     directory: focusPath,
     cwd: deps.cwd,

package/src/session/refactor-plans.ts

@@ -19,6 +19,8 @@ export interface RefactorPlan {
   targetLine: number;
   targetCharacter: number;
   edits: WorkspaceEdit;
+  /** Canonical roots that the routed semantic provider authorized. */
+  authorizedMutationRoots: string[];
   fileFingerprints: Array<{ file: string; fingerprint: string }>;
   createdAt: number;
 }

package/src/session/refactor-workflow.ts

@@ -7,7 +7,12 @@ import type {
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { toLspPosition } from "@mrclrchtr/supi-lsp/api";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import { applyWorkspaceEdit } from "../analysis/refactor/apply.ts";
+import {
+  establishMutationAuthority,
+  revalidateMutationAuthority,
+} from "../analysis/refactor/mutation-authority.ts";
 import { validateEdit } from "../analysis/refactor/safety.ts";
 import { normalizePath } from "../analysis/search/paths.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
@@ -66,7 +71,9 @@ export async function runRefactorPlanWorkflow(
       nameAnchorRequired: parsed.operation === "rename_symbol",
     },
     deps,
+    control,
   );
+  throwIfAborted(control);
   if (target.kind === "target-group") {
     return {
       kind: "invalid-input",
@@ -81,24 +88,29 @@ export async function runRefactorPlanWorkflow(
   }
   if (target.kind !== "resolved") return target;
 
-  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
-    kind: "file",
-    file: target.entry.file,
-  });
+  const readiness = await deps.capability.ensureSemanticReadiness(
+    deps.cwd,
+    { kind: "file", file: target.entry.file },
+    control,
+  );
   if (readiness.kind === "timeout") {
-    return { kind: "unavailable", reason: "Semantic readiness timed out." };
+    return { kind: "unavailable", reason: SEMANTIC_READINESS_TIMEOUT_REASON };
   }
   if (readiness.kind === "unavailable") return readiness;
   throwIfAborted(control);
 
   const file = normalizePath(target.entry.file, deps.cwd);
-  const result = await planWithProvider(deps.capability.getSemanticProvider(deps.cwd), {
-    operation: parsed.operation,
-    file,
-    position: toLspPosition(target.entry.displayLine, target.entry.displayCharacter),
-    range: parsed.range ? toLspRange(parsed.range) : undefined,
-    newName: parsed.newName,
-  });
+  const result = await planWithProvider(
+    deps.capability.getSemanticProvider(deps.cwd),
+    {
+      operation: parsed.operation,
+      file,
+      position: toLspPosition(target.entry.displayLine, target.entry.displayCharacter),
+      range: parsed.range ? toLspRange(parsed.range) : undefined,
+      newName: parsed.newName,
+    },
+    control,
+  );
   if (result.kind === "unavailable") return result;
   if (result.kind === "ambiguous") {
     return { kind: "ambiguous", candidates: result.candidates };
@@ -108,6 +120,11 @@ export async function runRefactorPlanWorkflow(
   if (!validation.safe) {
     return { kind: "invalid-input", message: `Refactor safety check failed: ${validation.reason}` };
   }
+  const authority = establishMutationAuthority(
+    result.edits.edits.map((edit) => edit.file),
+    result.authorizedMutationRoots,
+  );
+  if (authority.kind === "unavailable") return authority;
 
   const plan: RefactorPlan = {
     id: generatePlanId(
@@ -123,6 +140,7 @@ export async function runRefactorPlanWorkflow(
     targetLine: target.entry.displayLine,
     targetCharacter: target.entry.displayCharacter,
     edits: result.edits,
+    authorizedMutationRoots: authority.canonicalRoots,
     fileFingerprints: collectFileFingerprints(result.edits.edits),
     createdAt: Date.now(),
   };
@@ -147,6 +165,11 @@ export async function runRefactorApplyWorkflow(
     };
   }
 
+  const authority = revalidateMutationAuthority(
+    plan.edits.edits.map((edit) => edit.file),
+    plan.authorizedMutationRoots,
+  );
+  if (authority.kind === "unavailable") return authority;
   const freshness = isPlanFresh(plan);
   if (!freshness.fresh) return { kind: "invalid-input", message: freshness.reason };
   const validation = validateEdit(plan.edits);
@@ -161,12 +184,26 @@ export async function runRefactorApplyWorkflow(
   const expectedFingerprints = new Map(
     plan.fileFingerprints.map(({ file, fingerprint }) => [file, fingerprint]),
   );
-  const result = await applyWorkspaceEdit(plan.edits, { expectedFingerprints });
+  const getOpenDocumentVersion = getDocumentVersionReader(deps);
+  const result = await applyWorkspaceEdit(plan.edits, {
+    authorizedMutationRoots: plan.authorizedMutationRoots,
+    expectedFingerprints,
+    getOpenDocumentVersion,
+  });
   if (result.kind === "error") return { kind: "unavailable", reason: result.reason };
   deps.removePlan(plan.id);
   return { kind: "completed", plan: immutablePlan(plan), result };
 }
 
+function getDocumentVersionReader(
+  deps: RefactorWorkflowDeps,
+): ((file: string) => number | null) | undefined {
+  const state = deps.capability.getLspRuntimeState(deps.cwd);
+  if (state.kind !== "ready" && state.kind !== "inactive") return undefined;
+  if (typeof state.runtime.getOpenDocumentVersion !== "function") return undefined;
+  return (file) => state.runtime.getOpenDocumentVersion(file);
+}
+
 function parseOperation(input: RefactorOperationInput):
   | {
       kind: "ok";
@@ -230,11 +267,12 @@ async function planWithProvider(
     range?: SourceRange;
     newName: string;
   },
+  control?: WorkflowControl,
 ): Promise<RefactorResult> {
   if (!provider) return { kind: "unavailable", reason: "No semantic provider is active." };
-  if (provider.refactor) return provider.refactor(request);
+  if (provider.refactor) return provider.refactor(request, control);
   if (request.operation === "rename_symbol" && provider.rename) {
-    return provider.rename(request.file, request.position, request.newName);
+    return provider.rename(request.file, request.position, request.newName, control);
   }
   return {
     kind: "unavailable",
@@ -255,7 +293,15 @@ function immutablePlan(plan: RefactorPlan): Readonly<RefactorPlan> {
     edits: Object.freeze({
       ...plan.edits,
       edits: Object.freeze(plan.edits.edits.map((edit) => Object.freeze({ ...edit }))),
+      documentPreconditions: plan.edits.documentPreconditions
+        ? Object.freeze(
+            plan.edits.documentPreconditions.map((precondition) =>
+              Object.freeze({ ...precondition }),
+            ),
+          )
+        : undefined,
     }),
+    authorizedMutationRoots: Object.freeze([...plan.authorizedMutationRoots]),
     fileFingerprints: Object.freeze(
       plan.fileFingerprints.map((fingerprint) => Object.freeze({ ...fingerprint })),
     ),