@mrclrchtr/supi-lsp 11.4.0 → 12.0.0

package/README.md

@@ -59,8 +59,8 @@ A configured route is not a ready server. Features depend on the active server,
 | Hover, definitions, references, implementations, document/workspace symbols | Supported through the server's corresponding LSP methods; availability and coverage differ by server. |
 | Diagnostics | Native pull, the eligible TypeScript request adapter, or ambient push. Push observation alone cannot confirm that a file is clean. See the diagnostic policy below. |
 | `rename_symbol` | Requires server rename support and validated text edits; uses `prepareRename` when advertised. |
-| `update_imports` / `delete_dead_code` | Requires matching `source.organizeImports` / (`source.removeUnused` or `source.removeUnusedImports`) code actions that produce validated text edits. Imports-only advertisement reports limited support, not arbitrary unused-declaration removal. |
-| `extract_function` / `extract_variable` | Unavailable for all languages: standard LSP code actions do not provide a safe exact extraction-name contract. |
+| `code_action` | Requires a code action of the requested `refactor*` kind for the range that produces validated text edits, directly or by capturing the one edit its command pushes. Names generated by the server appear unchanged in the plan. |
+| `source_action` | Requires a code action of the requested `source*` kind for the whole document that produces validated text edits, directly or (for `source.organizeImports` and `source.fixAll`) by capturing the one edit its command pushes. |
 
 The [operation-support model](src/config/operation-support.ts) separates server advertisement from SuPi planning limits. A server can advertise an action that SuPi cannot safely turn into a plan.
 
@@ -106,7 +106,7 @@ The required [Linux/macOS CI matrix](../../.github/workflows/ci.yml) keeps [sele
 
 [Bounded config comparisons](__tests__/integration/typescript-config-coverage.test.ts) compare TS6 and native TS7 `--showConfig` root-file coverage for TS/JS defaults, include/exclude, `allowJs`/`checkJs`, inherited patterns (including late-created files), and separate referenced projects. These cases found no false exclusion; filtering is unchanged. **Config coverage state is not TypeScript program membership**: imports may bring excluded files into a program, and references do not merge root-file lists.
 
-Native `delete_dead_code` consumes `source.removeUnusedImports` through the same safe plan/apply workflow ([#554](https://github.com/mrclrchtr/supi/issues/554)). This mapping removes unused imports only: operation support reports `server: advertised`, `supi: limited`, with an imports-only reason. It does not qualify arbitrary unused-declaration removal. Extraction remains unavailable ([#467](https://github.com/mrclrchtr/supi/issues/467)); no TLS/native feature-parity claim is made. Only the pinned combinations are tested, not every stable TS7 release. Focused qualification passed on macOS arm64 (Node 24.22.1) and Linux arm64 (Debian container, Node 24.22.0), including the native/TS6 public TS/JS matrix. The unused-import follow-up has local macOS arm64 verification only; its Linux verification remains pending. The pinned Linux/macOS CI jobs remain pending until they run; this is not a qualification claim for the complete multi-language baseline.
+Native TypeScript 7 offers `source.removeUnusedImports` through the same safe plan/apply workflow ([#554](https://github.com/mrclrchtr/supi/issues/554)); it removes unused imports only, not arbitrary unused declarations. Native TypeScript 7 advertises no `refactor*` kinds, so `code_action` extraction is unavailable there; no TLS/native feature-parity claim is made. Only the pinned combinations are tested, not every stable TS7 release. Focused qualification passed on macOS arm64 (Node 24.22.1) and Linux arm64 (Debian container, Node 24.22.0), including the native/TS6 public TS/JS matrix. The unused-import follow-up has local macOS arm64 verification only; its Linux verification remains pending. The pinned Linux/macOS CI jobs remain pending until they run; this is not a qualification claim for the complete multi-language baseline.
 
 ### Java startup and project JDKs
 
@@ -320,21 +320,26 @@ Disable one language with `lsp.servers.<language>.enabled: false`. Use `/supi-ci
 - explicit ready, pending, inactive, disabled, and unavailable registry states
 - a `SemanticProvider` adapter for `supi-code-runtime`
 - precise rename and code-action edit conversion
-- operation-specific code-action kind filters and standard lazy edit resolution
+- code-action kind-prefix filters, exact-title selection, and standard lazy edit resolution
 - negotiated operation support in project-server status
 
-Operation-specific planners request `source.organizeImports` for import updates and
-both `source.removeUnused` and `source.removeUnusedImports` for dead-code removal.
-These distinct kinds are alternatives, not parent/child kinds; either exact kind
-or its dotted descendants can match the returned `CodeAction.kind`, never its title.
-An imports-only advertisement reports a SuPi limitation rather than general
-unused-declaration support. Edit-only actions are validated before planning. Command actions,
-resource operations, snippets, annotations, malformed actions, and stale responses
-stay unavailable. Distinct matching plans return an ambiguous result instead of
-selecting the first action. Rename uses `prepareRename` when the server advertises
-it and otherwise uses direct standard rename. Standard LSP does not provide
-a safe exact extraction-name contract, so `extract_function` and `extract_variable`
-plans report a SuPi planning limitation instead of selecting a generated name.
+Code- and source-action planners request exactly the caller's kind with `only` and
+match the returned `CodeAction.kind` or its dotted descendants, never the title.
+Entries outside `only` are dropped before validation. Disabled actions never match;
+an optional exact title narrows the matches. Edit-only actions are validated before
+planning. One eligible command-only action (`refactor*`, `source.organizeImports*`,
+`source.fixAll*`; a command the server lists when it lists any) runs once: SuPi
+advertises `workspace.applyEdit`, refuses every pushed edit with `applied: false`,
+and plans the single edit captured while the command runs or shortly after it
+answers, even when the server then reports the command as failed because the
+edit was refused (clangd does). A timed-out or cancelled command keeps refusing late edits until it
+settles. Touched open documents are re-sent as full text under a new version.
+Running a command may still change server-side state. Resource operations,
+snippets, annotations, malformed actions, and stale responses stay unavailable. Distinct matching plans return an
+ambiguous result with each candidate's kind and title instead of selecting the first
+action. Rename uses `prepareRename` when the server advertises it and otherwise uses
+direct standard rename. Code actions choose generated names; plans preview them as
+the server returns them.
 
 Rename responses that need additional document state can trigger one bounded discovery/enrollment retry. SuPi validates edit shape and canonical mutation paths, enrolls at most 64 affected files on the same route, and requests fresh edits. The first response is not a plan. Numeric versions must still match. A null version for an open document requires verified synchronized-content evidence; the plan retains the request fingerprint and client version. Missing snapshots, changed inputs, a larger follow-up edit set, and unsafe edits remain unavailable. Planning and apply revalidate these preconditions; no version is discarded to make an edit fit.
 

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "11.4.0",
+  "version": "12.0.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts

@@ -60,6 +60,7 @@ export type {
   ImportData,
   NodeAtData,
   OutlineData,
+  RefactorActionIdentity,
   RefactorOperation,
   RefactorRequest,
   RefactorResult,

package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts

@@ -193,31 +193,53 @@ export interface WorkspaceEdit {
 }
 
 /**
- * Supported refactor operation names for the current semantic planning path.
- */
-export type RefactorOperation =
-  | "rename_symbol"
-  | "extract_function"
-  | "extract_variable"
-  | "rename_file"
-  | "move_file"
-  | "update_imports"
-  | "delete_dead_code";
-
-/**
- * Operation-aware refactor planning request.
+ * Operation-aware refactor planning request. Each operation carries only the
+ * scope it needs:
  *
- * Consumers provide a target file/position plus operation-specific options.
- * File/resource operations remain requestable so providers can reject them
- * explicitly and honestly until shared workspace-edit resource ops exist.
+ * - `rename_symbol`: one symbol position and the new name.
+ * - `code_action`: one file range and a CodeActionKind prefix under `refactor`.
+ * - `source_action`: one whole file and a CodeActionKind prefix under `source`.
+ *
+ * `kind` matches the requested kind and its dotted sub-kinds. `title`, when
+ * present, selects one action by its exact title.
  */
-export interface RefactorRequest {
-  operation: RefactorOperation;
-  file: string;
-  position: CodePosition;
-  range?: SourceRange;
-  newName?: string;
-  destination?: string;
+export type RefactorRequest =
+  | {
+      operation: "rename_symbol";
+      file: string;
+      position: CodePosition;
+      newName: string;
+    }
+  | {
+      operation: "code_action";
+      file: string;
+      range: SourceRange;
+      kind: string;
+      title?: string;
+    }
+  | {
+      operation: "source_action";
+      file: string;
+      kind: string;
+      title?: string;
+    };
+
+/** Supported refactor operation names. */
+export type RefactorOperation = RefactorRequest["operation"];
+
+/** The code action selected for a precise code- or source-action plan. */
+export interface RefactorActionIdentity {
+  /** Server-reported CodeActionKind. */
+  kind: string;
+  /** Server-reported action title. */
+  title: string;
+  /**
+   * How the edits were obtained: `edit` from the action itself (after
+   * `codeAction/resolve` when needed), or `captured-command` from the single
+   * `workspace/applyEdit` the server pushed while running the action's command.
+   * Captured edits were refused, never applied.
+   */
+  provenance?: "edit" | "captured-command";
 }
 
 /**
@@ -228,6 +250,10 @@ export interface DisambiguationCandidate {
   file?: string;
   line?: number;
   character?: number;
+  /** Server-reported CodeActionKind, for code-action candidates. */
+  kind?: string;
+  /** Exact action title to pass back as `title`, for code-action candidates. */
+  title?: string;
 }
 
 /**
@@ -241,6 +267,8 @@ export type RefactorResult =
   | {
       kind: "precise";
       edits: WorkspaceEdit;
+      /** The selected code action, for code- and source-action plans. */
+      action?: RefactorActionIdentity;
       /** Provider roots authorized by the semantic route. Consumers canonicalize before storage. */
       authorizedMutationRoots: string[];
     }

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "11.4.0",
+  "version": "12.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "11.4.0",
+  "version": "12.0.0",
   "description": "Language Server Protocol runtime for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "vscode-jsonrpc": "^10.0.0",
     "vscode-languageserver-protocol": "^3.18.5",
     "vscode-languageserver-types": "^3.18.5",
-    "@mrclrchtr/supi-code-runtime": "11.4.0",
-    "@mrclrchtr/supi-core": "11.4.0"
+    "@mrclrchtr/supi-code-runtime": "12.0.0",
+    "@mrclrchtr/supi-core": "12.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/api.ts

@@ -1,5 +1,6 @@
 // Public API surface for the LSP session-scoped service.
 
+export type { CommandEditCaptureResult } from "./client/client-edit-capture.ts";
 export { isMissingFileError } from "./client/client-file-state.ts";
 export {
   getExplicitlyDisabledLanguages,
@@ -7,10 +8,8 @@ export {
   loadConfig,
 } from "./config/config.ts";
 export {
-  codeActionKindsForOperation,
   getServerOperationSupport,
   isCodeActionKindInRange,
-  REFACTOR_CODE_ACTION_KINDS,
   supportsCodeActionResolve,
   supportsCodeActions,
   supportsPrepareRename,
@@ -91,6 +90,7 @@ export type {
   ProcessCrashRecoveryOutcome,
   ProcessCrashRecoveryReport,
   RecoverDiagnosticsResult,
+  RoutedCodeActionResponse,
   RoutedMutationDocumentSnapshot,
   RoutedMutationResponse,
   SemanticReadinessResult,

package/src/client/client-diagnostic-capabilities.ts

@@ -7,6 +7,7 @@
 // dynamic set for `textDocument/diagnostic` is non-empty.
 
 import { posix as posixPath } from "node:path";
+import type { CFamilyFileAssociationResolver } from "@mrclrchtr/supi-code-runtime/api";
 import { uriToFile } from "@mrclrchtr/supi-core/path";
 import { detectLanguageId } from "../utils.ts";
 
@@ -51,12 +52,21 @@ export function isValidDocumentSelector(value: unknown): boolean {
   );
 }
 
-/** Match one valid document selector against a file URI. */
-export function isDocumentSelectorApplicable(selector: unknown, uri: string): boolean {
+/**
+ * Match one valid document selector against a file URI.
+ *
+ * Pass the client's file associations so the language matches the ID sent in
+ * `didOpen` (for example, a `.h` file associated with `cpp`).
+ */
+export function isDocumentSelectorApplicable(
+  selector: unknown,
+  uri: string,
+  associations?: CFamilyFileAssociationResolver,
+): boolean {
   if (selector === undefined || selector === null) return true;
   if (!isValidDocumentSelector(selector)) return false;
   if (!Array.isArray(selector) || selector.length === 0) return false;
-  const language = detectLanguageId(uriToFile(uri));
+  const language = detectLanguageId(uriToFile(uri), associations);
   const scheme = readUriScheme(uri);
   const filePath = uriToFile(uri).replaceAll("\\", "/");
   return selector.some((entry) => {

package/src/client/client-diagnostics.ts

@@ -237,22 +237,17 @@ export class ClientDiagnostics {
     for (const update of updates) {
       const document = this.#openDocs.get(update.document.uri);
       if (!document) throw new Error("Semantic input changed while synchronization was running.");
-      this.#synchronizeTrackedDocument(
-        update.document.uri,
-        update.document.filePath,
-        update.content,
-        document,
-      );
+      this.#synchronizeTrackedDocument(update.document, update.content, document);
       this.#failedUris.delete(update.document.uri);
     }
   }
 
   /** Apply one tracked-document change with the shared client state. */
   #synchronizeTrackedDocument(
-    uri: string,
-    filePath: string,
+    { uri, filePath }: { readonly uri: string; readonly filePath: string },
     content: string,
     document: OpenDocumentState,
+    options: { fullText?: boolean } = {},
   ): void {
     synchronizeTrackedDocument({
       uri,
@@ -267,6 +262,7 @@ export class ClientDiagnostics {
       markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
       clearFailedFile: () => this.#failedUris.delete(uri),
       open: () => this.didOpen(filePath, content),
+      ...(options.fullText ? { fullText: true } : {}),
     });
   }
 
@@ -394,7 +390,27 @@ export class ClientDiagnostics {
     const nextFingerprint = fingerprintDocumentContent(content);
     if (doc.contentFingerprint === nextFingerprint) return;
     this.#advanceInputRevision();
-    this.#synchronizeTrackedDocument(uri, filePath, content, doc);
+    this.#synchronizeTrackedDocument({ uri, filePath }, content, doc);
+  }
+
+  /**
+   * Re-send an open document's tracked content under a new version, even when
+   * it is unchanged. The tracked content matches disk: semantic requests
+   * synchronize open documents with disk before they run. Used after a server ran a command whose pushed
+   * edit was refused, so the server's model matches the client again.
+   * Returns the versions before and after, or null when the document is not open.
+   */
+  resynchronizeOpenDocument(filePath: string): { from: number; to: number } | null {
+    if (!this.host.isOperational()) return null;
+    const uri = fileToUri(filePath);
+    const doc = this.#openDocs.get(uri);
+    if (!doc) return null;
+    const from = doc.version;
+    this.#advanceInputRevision();
+    // Full text: the server may have changed its own copy, so a range computed
+    // from the client's content could no longer cover the whole document.
+    this.#synchronizeTrackedDocument({ uri, filePath }, doc.content, doc, { fullText: true });
+    return { from, to: doc.version };
   }
 
   /** Send a save after a disk change that the input barrier observed. */

package/src/client/client-document-sync.ts

@@ -73,6 +73,8 @@ interface SynchronizeDocumentOptions {
   documentSync: NormalizedDocumentSync;
   waiters: DiagnosticWaitRegistry;
   sendNotification: NotificationSender;
+  /** Send the whole text without a range, even under incremental sync (LSP allows both). */
+  fullText?: boolean;
 }
 
 function endPosition(content: string): { line: number; character: number } {
@@ -117,11 +119,9 @@ export function synchronizeDocument(options: SynchronizeDocumentOptions): void {
   retainDocumentSynchronization(options);
   options.document.version = options.version;
   options.document.synchronizationId = options.synchronizationId;
-  const changes = contentChanges(
-    options.document.content,
-    options.content,
-    options.documentSync.change,
-  );
+  const changes = options.fullText
+    ? [{ text: options.content }]
+    : contentChanges(options.document.content, options.content, options.documentSync.change);
   options.document.content = options.content;
   options.document.contentFingerprint = fingerprintDocumentContent(options.content);
   if (options.documentSync.change === TextDocumentSyncKind.None) return;
@@ -161,6 +161,7 @@ export function synchronizeTrackedDocument(options: {
   markUnversionedSyncMoment?(): void;
   clearFailedFile?(): void;
   open(): void;
+  fullText?: boolean;
 }): void {
   if (!options.document) {
     options.open();
@@ -177,6 +178,7 @@ export function synchronizeTrackedDocument(options: {
     documentSync: options.documentSync,
     waiters: options.waiters,
     sendNotification: options.sendNotification,
+    ...(options.fullText ? { fullText: true } : {}),
   });
   options.clearFailedFile?.();
 }

package/src/client/client-edit-capture.ts

@@ -0,0 +1,258 @@
+/**
+ * Capture window for server-pushed `workspace/applyEdit` requests.
+ *
+ * SuPi never applies an edit that a server pushes. While one command runs for
+ * preview, each pushed edit is recorded and refused; outside that window every
+ * pushed edit is refused as unsolicited (LSP 3.17 `ApplyWorkspaceEditResult`).
+ */
+
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+import type { Command, WorkspaceEdit } from "../config/types.ts";
+import { LSP_REQUEST_TIMEOUT_ERROR_CODE } from "../debug-telemetry.ts";
+import { JsonRpcRequestError } from "./transport.ts";
+
+/** Reply for an edit recorded for preview. */
+export const CAPTURED_EDIT_REPLY = {
+  applied: false,
+  failureReason: "SuPi captured this edit for preview.",
+} as const;
+
+/** Reply for an edit that arrives outside a capture window. */
+export const UNSOLICITED_EDIT_REPLY = {
+  applied: false,
+  failureReason: "SuPi does not accept unsolicited workspace edits.",
+} as const;
+
+/** Result of running one command inside a capture window. */
+export type CommandEditCaptureResult =
+  | {
+      readonly kind: "captured";
+      /** The single edit the server pushed while the command ran. */
+      readonly edit: WorkspaceEdit;
+      /** Open documents re-sent afterwards, with their versions before and after. */
+      readonly resynced: readonly { file: string; from: number; to: number }[];
+    }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/** Reply for an edit from a command SuPi stopped waiting for. */
+export const ABANDONED_EDIT_REPLY = {
+  applied: false,
+  failureReason: "SuPi stopped waiting for the command that produced this edit.",
+} as const;
+
+/**
+ * Records pushed edits for at most one capture per client. After a capture
+ * stops waiting (timeout, abort, deadline) the window keeps draining until the
+ * abandoned command settles, so its late edits are refused and can never be
+ * attributed to the next capture.
+ */
+export class EditCaptureWindow {
+  #state: "idle" | "capturing" | "draining" = "idle";
+  #edits: unknown[] = [];
+  #onEdit: (() => void) | undefined;
+
+  /** Open the window. Returns false while another capture runs or drains. */
+  open(): boolean {
+    if (this.#state !== "idle") return false;
+    this.#state = "capturing";
+    this.#edits = [];
+    return true;
+  }
+
+  /** Stop capturing and return the edits pushed so far. */
+  close(): unknown[] {
+    const edits = this.#edits;
+    this.#edits = [];
+    this.#onEdit = undefined;
+    if (this.#state === "capturing") this.#state = "idle";
+    return edits;
+  }
+
+  /** Stop capturing but refuse new captures until `settled` resolves. */
+  drain(settled: Promise<void>): unknown[] {
+    const edits = this.close();
+    this.#state = "draining";
+    void settled.then(() => {
+      if (this.#state === "draining") this.#state = "idle";
+    });
+    return edits;
+  }
+
+  /** Wait up to `ms` for the first edit when none has arrived yet. */
+  async waitForEdit(ms: number): Promise<void> {
+    if (this.#edits.length > 0 || ms <= 0) return;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      this.#onEdit = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    });
+  }
+
+  /** Answer one `workspace/applyEdit` request; the edit is never applied. */
+  handleApplyEdit(
+    params: unknown,
+  ): typeof CAPTURED_EDIT_REPLY | typeof UNSOLICITED_EDIT_REPLY | typeof ABANDONED_EDIT_REPLY {
+    if (this.#state === "draining") return ABANDONED_EDIT_REPLY;
+    if (this.#state === "idle") return UNSOLICITED_EDIT_REPLY;
+    const edit =
+      typeof params === "object" && params !== null
+        ? (params as { edit?: unknown }).edit
+        : undefined;
+    this.#edits.push(edit);
+    this.#onEdit?.();
+    return CAPTURED_EDIT_REPLY;
+  }
+}
+
+/** Collect the file URIs a captured edit touches, for resynchronization. */
+export function editedDocumentUris(edit: unknown): string[] {
+  if (typeof edit !== "object" || edit === null) return [];
+  const uris = new Set<string>();
+  const { changes, documentChanges } = edit as {
+    changes?: unknown;
+    documentChanges?: unknown;
+  };
+  if (typeof changes === "object" && changes !== null) {
+    for (const uri of Object.keys(changes)) uris.add(uri);
+  }
+  if (Array.isArray(documentChanges)) {
+    for (const change of documentChanges) {
+      const uri = (change as { textDocument?: { uri?: unknown } } | null)?.textDocument?.uri;
+      if (typeof uri === "string") uris.add(uri);
+    }
+  }
+  return [...uris];
+}
+
+/** Default wait for an edit a server pushes just after answering the command. */
+const DEFAULT_GRACE_MS = 250;
+
+/** Collaborators for one command capture on one client. */
+export interface CommandEditCaptureOptions {
+  readonly command: Command;
+  /** Upper bound for the command to finish. */
+  readonly timeoutMs: number;
+  /** Wait for an edit pushed after the command answers; LSP allows that order. */
+  readonly graceMs?: number;
+  /** Upper bound for refusing late edits from an abandoned command. */
+  readonly drainMs?: number;
+  readonly control?: CodeRequestControl;
+  readonly window: EditCaptureWindow;
+  /** Send one request and expose when its transport lifetime ends. */
+  sendRequestOwned(
+    method: string,
+    params: unknown,
+    options: { timeoutMs: number } & CodeRequestControl,
+  ): { result: Promise<unknown>; settled: Promise<void> };
+  /** Re-send one open document; null when it is not open. */
+  resynchronize(file: string): { from: number; to: number } | null;
+}
+
+/**
+ * Run one command inside a capture window. Exactly one pushed edit becomes the
+ * result; none, several, a timeout, or a server error are unavailable.
+ * Cancellation and deadline expiry propagate. Every touched open document is
+ * resynced, and an abandoned command keeps the window draining.
+ */
+export async function runCommandEditCapture(
+  options: CommandEditCaptureOptions,
+): Promise<CommandEditCaptureResult> {
+  const { command, timeoutMs, control, window } = options;
+  if (!window.open()) {
+    return {
+      kind: "unavailable",
+      reason: "Another server command capture is running on this client; retry shortly.",
+    };
+  }
+  const request = options.sendRequestOwned(
+    "workspace/executeCommand",
+    { command: command.command, ...(command.arguments ? { arguments: command.arguments } : {}) },
+    { ...control, timeoutMs },
+  );
+  let serverError: string | undefined;
+  try {
+    await request.result;
+  } catch (error) {
+    if (!(error instanceof JsonRpcRequestError) || isCodeRequestInterruption(error, control)) {
+      return abandonCapture(options, request.settled, error);
+    }
+    // The server answered with an error, so the command is over. clangd
+    // reports that the refused edit "was not applied"; the edit still counts.
+    serverError = error.message;
+  }
+  if (serverError === undefined) await window.waitForEdit(options.graceMs ?? DEFAULT_GRACE_MS);
+  const edits = window.close();
+  const resynced = resynchronizeEdits(edits, options.resynchronize);
+  if (edits.length === 0) {
+    return {
+      kind: "unavailable",
+      reason:
+        serverError === undefined
+          ? "The server command produced no edit; there may be nothing to change."
+          : `The server command failed: ${serverError}`,
+    };
+  }
+  if (edits.length > 1) {
+    return {
+      kind: "unavailable",
+      reason: `The server command produced ${edits.length} edits; only one can be previewed.`,
+    };
+  }
+  return { kind: "captured", edit: edits[0] as WorkspaceEdit, resynced };
+}
+
+/** Close or drain the window after SuPi stopped waiting for the command, then report or rethrow. */
+function abandonCapture(
+  options: CommandEditCaptureOptions,
+  settled: Promise<void>,
+  error: unknown,
+): CommandEditCaptureResult {
+  const { window, timeoutMs, control } = options;
+  const drainMs = options.drainMs ?? timeoutMs;
+  const edits = drainMs > 0 ? window.drain(boundedSettle(settled, drainMs)) : window.close();
+  resynchronizeEdits(edits, options.resynchronize);
+  if (isCodeRequestInterruption(error, control)) throw error;
+  return {
+    kind: "unavailable",
+    reason: isTimeout(error)
+      ? `The server command did not finish within ${timeoutMs} ms.`
+      : `The server command could not run: ${error instanceof Error ? error.message : String(error)}`,
+  };
+}
+
+function boundedSettle(settled: Promise<void>, ms: number): Promise<void> {
+  return Promise.race([settled, new Promise<void>((resolve) => setTimeout(resolve, ms))]);
+}
+
+function resynchronizeEdits(
+  edits: readonly unknown[],
+  resynchronize: CommandEditCaptureOptions["resynchronize"],
+): { file: string; from: number; to: number }[] {
+  const uris = new Set(edits.flatMap((edit) => editedDocumentUris(edit)));
+  const resynced: { file: string; from: number; to: number }[] = [];
+  for (const uri of uris) {
+    let file: string;
+    try {
+      file = uriToFile(uri);
+    } catch {
+      continue;
+    }
+    const versions = resynchronize(file);
+    if (versions) resynced.push({ file, ...versions });
+  }
+  return resynced;
+}
+
+function isTimeout(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { code?: unknown }).code === LSP_REQUEST_TIMEOUT_ERROR_CODE
+  );
+}