@ian-pascoe/pi-lsp 0.1.1 → 0.2.0

package/README.md

@@ -102,8 +102,9 @@ UTF-32 encoding. `selection_ranges` accepts a `positions` array. `find_reference
 `workspace_symbols` requires `query` and a root-anchor `file_path`. `workspace_diagnostics`,
 `capabilities`, and `restart` require `server_id` and a root-anchor `file_path`. Other reads query
 every matching capable server unless narrowed by `server_id`; successful responses remain visible
-when another server fails. A mutation may omit `server_id` only when exactly one matching capable
-server exists.
+when another server fails. Automatic reads omit matching incapable servers and fail once if none
+are capable; explicitly selecting an incapable server reports that the operation is unsupported. A
+mutation may omit `server_id` only when exactly one matching capable server exists.
 
 Formatting requires `tab_size` and `insert_spaces`. It optionally accepts
 `trim_trailing_whitespace`, `insert_final_newline`, and `trim_final_newlines`. Range formatting also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-lsp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "Configured language-server tools and post-edit diagnostics for Pi",
   "keywords": [
@@ -22,6 +22,7 @@
   },
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -48,6 +49,9 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "scripts": {

package/skills/pi-lsp/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pi-lsp
+description: Configure or diagnose Pi LSP when a Server Definition fails, a file does not route, diagnostics are missing, or lsp settings need changing.
+license: MIT
+---
+
+# Pi LSP
+
+1. Read [`../../README.md`](../../README.md)'s Settings and `lsp` tool sections, then identify the effective settings scope.
+2. Call `lsp` with `{"operation":"status"}`.
+3. Test a representative file with `capabilities`, then `diagnostics`, supplying `server_id` when needed.
+4. Classify the result as settings, routing, process, capability, or Post-edit Diagnostics behavior.
+5. If settings changed, reload Pi; if settings are unchanged and the Server Instance is unavailable, use `restart`.
+6. Repeat status, capabilities, and diagnostics. Finish when the representative file reaches the intended Server Instance and operation, or an exact unsupported capability is evidenced.
+
+`configured` has not routed a file yet. `unavailable` is sticky and retains stderr. Keep diagnosis read-only; stop before applying a Workspace Edit Preview.

package/src/lsp-position-encoding.ts

@@ -24,7 +24,8 @@ export function normalizeLspPositionEncoding(encoding: string | undefined): LspP
   return "utf-16";
 }
 
-function documentLines(documentText: string): readonly string[] {
+/** Split document text into lines on CRLF, LF, or CR separators. */
+export function documentLines(documentText: string): readonly string[] {
   return documentText.split(/\r\n|[\n\r]/u);
 }
 

package/src/lsp-post-edit-diagnostics-rendering.ts

@@ -68,7 +68,8 @@ function severityColor(severity: DiagnosticSeverity): ThemeColor {
   }
 }
 
-function pluralizedCount(count: number, singular: string, plural = `${singular}s`): string {
+/** Render one count with a pluralized noun, e.g. `3 files` or `1 file`. */
+export function pluralizedCount(count: number, singular: string, plural = `${singular}s`): string {
   return `${count} ${count === 1 ? singular : plural}`;
 }
 

package/src/lsp-post-edit-diagnostics.ts

@@ -98,28 +98,9 @@ export const PostEditDiagnosticOutcomeSchema = Type.Union([
 export type PostEditDiagnosticOutcome = Static<typeof PostEditDiagnosticOutcomeSchema>;
 
 /** Runs fresh Post-edit Diagnostics for changed paths after a Supported Mutation Tool result. */
-export interface PostEditDiagnosticsRunner {
-  /** Return every fresh diagnostic and explicit non-diagnostic outcome for the supplied paths. */
-  runPostEditDiagnostics(
-    paths: readonly PostEditDiagnosticPath[],
-  ): Promise<readonly PostEditDiagnosticOutcome[]>;
-}
-
-/** Minimal Tool Result shape accepted by the structural post-edit adapters. */
-export interface PostEditToolResult {
-  /** Tool name supplied by Pi's central tool-result event. */
-  readonly toolName: string;
-  /** Original tool arguments supplied to the central event. */
-  readonly input: ToolResultEvent["input"];
-  /** Tool-result details owned by the mutation implementation. */
-  readonly details: ToolResultEvent["details"];
-  /** Existing Pi content, retained verbatim before the appended LSP section. */
-  readonly content: ToolResultEvent["content"];
-  /** Existing tool failure state, which diagnostics must not change. */
-  readonly isError: boolean;
-  /** Existing usage accounting, which diagnostics must not change. */
-  readonly usage?: ToolResultEvent["usage"];
-}
+export type PostEditDiagnosticsRunner = (
+  paths: readonly PostEditDiagnosticPath[],
+) => Promise<readonly PostEditDiagnosticOutcome[]>;
 
 /** Tool-result fields returned by Post-edit Diagnostics middleware without changing mutation state. */
 export interface PostEditDiagnosticsResultPatch {
@@ -174,7 +155,7 @@ function pathsAfterMutation(result: ReturnType<typeof mutationResult>): PostEdit
 
 /** Extract exact changed destination paths from one Supported Mutation Tool result. */
 export function extractPostEditDiagnosticPaths(
-  event: Pick<PostEditToolResult, "toolName" | "input" | "details" | "isError">,
+  event: Pick<ToolResultEvent, "toolName" | "input" | "details" | "isError">,
 ): ExtractedMutation | undefined {
   if (event.toolName === "edit" || event.toolName === "write") {
     if (event.isError || !Value.Check(NativeMutationInputSchema, event.input)) return undefined;
@@ -261,7 +242,7 @@ export function formatPostEditDiagnostics(outcomes: readonly PostEditDiagnosticO
 
 /** Append fresh Post-edit Diagnostics while preserving every mutation-result field Pi already owns. */
 export async function appendPostEditDiagnostics(
-  event: PostEditToolResult,
+  event: ToolResultEvent,
   diagnostics: PostEditDiagnosticsRunner,
 ): Promise<PostEditDiagnosticsResultPatch | undefined> {
   const extracted = extractPostEditDiagnosticPaths(event);
@@ -271,7 +252,7 @@ export async function appendPostEditDiagnostics(
       kind: "warning",
       message,
     })),
-    ...(await diagnostics.runPostEditDiagnostics(extracted.paths)),
+    ...(await diagnostics(extracted.paths)),
   ];
   if (outcomes.length === 0) return undefined;
   const patch: PostEditDiagnosticsResultPatch = {
@@ -282,11 +263,3 @@ export async function appendPostEditDiagnostics(
   };
   return event.usage === undefined ? patch : { ...patch, usage: event.usage };
 }
-
-/** Adapt Pi's central ToolResultEvent shape to Post-edit Diagnostics middleware. */
-export async function appendPiPostEditDiagnostics(
-  event: ToolResultEvent,
-  diagnostics: PostEditDiagnosticsRunner,
-): Promise<PostEditDiagnosticsResultPatch | undefined> {
-  return appendPostEditDiagnostics(event, diagnostics);
-}

package/src/lsp-server-client.ts

@@ -48,10 +48,12 @@ import {
   type WorkspaceEdit,
 } from "vscode-languageserver-protocol/node";
 import {
+  documentLines,
   measureLspPositionCharacters,
   normalizeLspPositionEncoding,
   type LspPositionEncoding,
 } from "./lsp-position-encoding.js";
+import type { LspTimeouts } from "./pi-lsp-settings.js";
 
 const MAX_OPEN_DOCUMENTS = 100;
 const MAX_STDERR_BYTES = 1024 * 1024;
@@ -79,16 +81,7 @@ const PrepareRenameProviderSchema = Type.Object(
 );
 
 /** Time budgets, in milliseconds, for one language-server process. */
-export interface LspServerClientTimeouts {
-  /** Initialize request budget. */
-  readonly initializeMs: number;
-  /** Ordinary request budget. */
-  readonly requestMs: number;
-  /** Fresh diagnostics budget. */
-  readonly diagnosticsMs: number;
-  /** Graceful shutdown budget before process termination. */
-  readonly shutdownMs: number;
-}
+export type LspServerClientTimeouts = LspTimeouts;
 
 /** Launch and protocol configuration for one language-server process. */
 export interface LspServerClientOptions {
@@ -118,8 +111,6 @@ export interface LspServerClientOptions {
 
 /** A valid UTF-8 document synchronized with one server instance. */
 export interface LspSynchronizedDocument {
-  /** Absolute file path. */
-  readonly filePath: string;
   /** File URI sent to the server. */
   readonly uri: string;
   /** Monotonic document version local to this server instance. */
@@ -148,8 +139,6 @@ export type LspWorkspaceDiagnosticResult =
 
 /** Classified process, protocol, timeout, cancellation, and UTF-8 client failure. */
 export class LspServerClientError extends Error {
-  readonly _tag = "LspServerClientError" as const;
-
   /** Construct a stable Pi LSP client failure that always names the stderr capture. */
   constructor(
     readonly kind:
@@ -218,7 +207,7 @@ function serverWantsSave(capabilities: ServerCapabilities): boolean {
 }
 
 function protocolLineEndPosition(text: string, encoding: LspPositionEncoding): Position {
-  const lines = text.split(/\r\n|\r|\n/);
+  const lines = documentLines(text);
   const lineText = lines.at(-1) ?? "";
   return {
     line: lines.length - 1,
@@ -268,13 +257,12 @@ export class LspServerClient {
   private positionEncodingValue: LspPositionEncoding = "utf-16";
   private textDocumentSyncKind: TextDocumentSyncKind = TextDocumentSyncKind.None;
   private readonly openDocuments = new Map<string, OpenDocumentState>();
+  private readonly documentSynchronizations = new Map<string, Promise<LspSynchronizedDocument>>();
   private readonly pushDiagnostics = new Map<string, PushDiagnosticsState>();
   private readonly pullDiagnostics = new Map<string, PullDiagnosticsState>();
   private readonly dynamicRegistrations = new Map<string, Registration>();
   private readonly diagnosticWaiters = new Map<string, Set<() => void>>();
-  private readonly protocolMessages: string[] = [];
   private diagnosticsRevision = 0;
-  private diagnosticsRefreshRevision = 0;
   private stderrTail: Buffer<ArrayBufferLike> = Buffer.alloc(0);
   private stderrWrite = Promise.resolve();
   private closing = false;
@@ -381,11 +369,6 @@ export class LspServerClient {
     return this.options.stderrPath;
   }
 
-  /** Most recent bounded protocol log/show messages, oldest first. */
-  get recentProtocolMessages(): readonly string[] {
-    return this.protocolMessages;
-  }
-
   /** Whether a static or dynamically registered LSP method is available. */
   hasCapability(method: string): boolean {
     if (
@@ -525,8 +508,33 @@ export class LspServerClient {
     filePath: string,
     languageId: string,
   ): Promise<LspSynchronizedDocument> {
-    this.throwIfUnavailable();
     const absolutePath = resolve(filePath);
+    const uri = pathToFileURL(absolutePath).href;
+    const activeSynchronization = this.documentSynchronizations.get(uri);
+    const waitForActiveSynchronization =
+      activeSynchronization?.then(
+        () => undefined,
+        () => undefined,
+      ) ?? Promise.resolve();
+    const synchronization = waitForActiveSynchronization.then(() =>
+      this.synchronizeDocumentOnce(absolutePath, uri, languageId),
+    );
+    this.documentSynchronizations.set(uri, synchronization);
+    try {
+      return await synchronization;
+    } finally {
+      if (this.documentSynchronizations.get(uri) === synchronization) {
+        this.documentSynchronizations.delete(uri);
+      }
+    }
+  }
+
+  private async synchronizeDocumentOnce(
+    absolutePath: string,
+    uri: string,
+    languageId: string,
+  ): Promise<LspSynchronizedDocument> {
+    this.throwIfUnavailable();
     let text: string;
     try {
       const bytes = await readFile(absolutePath);
@@ -544,10 +552,13 @@ export class LspServerClient {
       throw cause;
     }
 
-    const uri = pathToFileURL(absolutePath).href;
     const existing = this.openDocuments.get(uri);
+    if (existing?.text === text && existing.languageId === languageId) {
+      this.openDocuments.delete(uri);
+      this.openDocuments.set(uri, existing);
+      return existing;
+    }
     const next: OpenDocumentState = {
-      filePath: absolutePath,
       uri,
       version: (existing?.version ?? 0) + 1,
       text,
@@ -622,7 +633,12 @@ export class LspServerClient {
     }
 
     try {
-      return await this.firstDiagnosticResult(candidates, signal);
+      return await this.raceBudget(
+        Promise.any(candidates),
+        this.options.timeouts.diagnosticsMs,
+        "diagnostics",
+        signal,
+      );
     } catch (cause) {
       if (cause instanceof LspServerClientError) {
         if (cause.kind === "cancelled") throw cause;
@@ -805,22 +821,13 @@ export class LspServerClient {
       }
     });
     this.connection.onRequest(WorkDoneProgressCreateRequest.type, () => undefined);
-    this.connection.onRequest(DiagnosticRefreshRequest.type, () => {
-      this.diagnosticsRefreshRevision++;
-    });
+    this.connection.onRequest(DiagnosticRefreshRequest.type, () => undefined);
     this.connection.onRequest(ApplyWorkspaceEditRequest.type, async (parameters) =>
       this.rejectServerWorkspaceEdit(parameters),
     );
-    this.connection.onRequest(ShowMessageRequest.type, (parameters) => {
-      this.rememberProtocolMessage(parameters.message);
-      return null;
-    });
-    this.connection.onNotification(LogMessageNotification.type, (parameters) => {
-      this.rememberProtocolMessage(parameters.message);
-    });
-    this.connection.onNotification(ShowMessageNotification.type, (parameters) => {
-      this.rememberProtocolMessage(parameters.message);
-    });
+    this.connection.onRequest(ShowMessageRequest.type, () => null);
+    this.connection.onNotification(LogMessageNotification.type, () => undefined);
+    this.connection.onNotification(ShowMessageNotification.type, () => undefined);
   }
 
   private async initialize(): Promise<void> {
@@ -923,30 +930,19 @@ export class LspServerClient {
     if (signal?.aborted === true) throw abortError(this.options);
 
     const cancellation = new CancellationTokenSource();
-    let timeout: NodeJS.Timeout | undefined;
-    let abortListener: (() => void) | undefined;
-    const request = this.connection.sendRequest<TResult>(method, parameters, cancellation.token);
-    const timeoutPromise = new Promise<never>((_resolve, reject) => {
-      timeout = setTimeout(() => {
-        cancellation.cancel();
-        reject(timeoutError(this.options, operation));
-      }, budgetMs);
-      timeout.unref();
-    });
-    const abortPromise = new Promise<never>((_resolve, reject) => {
-      if (signal === undefined) return;
-      abortListener = () => {
-        cancellation.cancel();
-        reject(abortError(this.options));
-      };
-      signal.addEventListener("abort", abortListener, { once: true });
-    });
-    const terminalPromise = this.terminalErrorPromise.then((error) => {
-      throw error;
-    });
-
     try {
-      return await Promise.race([request, timeoutPromise, abortPromise, terminalPromise]);
+      return await Promise.race([
+        this.raceBudget(
+          this.connection.sendRequest<TResult>(method, parameters, cancellation.token),
+          budgetMs,
+          operation,
+          signal,
+          () => cancellation.cancel(),
+        ),
+        this.terminalErrorPromise.then((error) => {
+          throw error;
+        }),
+      ]);
     } catch (cause) {
       if (cause instanceof LspServerClientError) throw cause;
       throw new LspServerClientError(
@@ -957,10 +953,6 @@ export class LspServerClient {
         { cause },
       );
     } finally {
-      if (timeout !== undefined) clearTimeout(timeout);
-      if (signal !== undefined && abortListener !== undefined) {
-        signal.removeEventListener("abort", abortListener);
-      }
       cancellation.dispose();
     }
   }
@@ -1047,34 +1039,29 @@ export class LspServerClient {
     return { status: "fresh", source: "document_pull", diagnostics: report.items };
   }
 
-  private async firstDiagnosticResult(
-    candidates: readonly Promise<LspDocumentDiagnosticResult>[],
-    signal?: AbortSignal,
-  ): Promise<LspDocumentDiagnosticResult> {
-    return this.raceBudget(
-      Promise.any(candidates),
-      this.options.timeouts.diagnosticsMs,
-      "diagnostics",
-      signal,
-    );
-  }
-
   private async raceBudget<TResult>(
     value: Promise<TResult>,
     budgetMs: number,
     operation: string,
     signal?: AbortSignal,
+    onCancel?: () => void,
   ): Promise<TResult> {
     if (signal?.aborted === true) throw abortError(this.options);
     let timeout: NodeJS.Timeout | undefined;
     let abortListener: (() => void) | undefined;
     const timeoutPromise = new Promise<never>((_resolve, reject) => {
-      timeout = setTimeout(() => reject(timeoutError(this.options, operation)), budgetMs);
+      timeout = setTimeout(() => {
+        onCancel?.();
+        reject(timeoutError(this.options, operation));
+      }, budgetMs);
       timeout.unref();
     });
     const abortPromise = new Promise<never>((_resolve, reject) => {
       if (signal === undefined) return;
-      abortListener = () => reject(abortError(this.options));
+      abortListener = () => {
+        onCancel?.();
+        reject(abortError(this.options));
+      };
       signal.addEventListener("abort", abortListener, { once: true });
     });
     try {
@@ -1167,11 +1154,6 @@ export class LspServerClient {
     }
   }
 
-  private rememberProtocolMessage(message: string): void {
-    this.protocolMessages.push(message);
-    if (this.protocolMessages.length > 100) this.protocolMessages.shift();
-  }
-
   private async evictOldDocuments(): Promise<void> {
     while (this.openDocuments.size > MAX_OPEN_DOCUMENTS) {
       const oldestUri = this.openDocuments.keys().next().value;

package/src/lsp-server-manager.ts

@@ -82,8 +82,6 @@ export interface LspServerFailure {
   readonly code: LspServerFailureCode;
   /** Searchable caller-facing error prefixed with `Pi LSP:`. */
   readonly message: string;
-  /** Selected workspace root when routing reached a concrete Server Instance. */
-  readonly rootPath?: string;
   /** Configured server ID, or the requested missing ID. */
   readonly serverId: string;
 }
@@ -100,7 +98,7 @@ export interface LspServerSuccess<T> {
 
 /** Keeps successful multi-server reads useful when independent servers fail. */
 export interface LspServerReadResult<T> {
-  /** Labeled failures in deterministic route order. */
+  /** Labeled operational failures in deterministic route order. */
   readonly failures: readonly LspServerFailure[];
   /** Labeled successful values in deterministic route order. */
   readonly successes: readonly LspServerSuccess<T>[];
@@ -135,8 +133,6 @@ export interface LspServerStatusEntry {
 
 /** Reports configuration failures and session-scoped Server Instance states. */
 export interface LspServerManagerStatus {
-  /** False when either authored `lsp` settings layer was malformed. */
-  readonly enabled: boolean;
   /** Server entries ordered by ID and then root. */
   readonly servers: readonly LspServerStatusEntry[];
   /** Strict settings failures kept visible until Pi `/reload`. */
@@ -248,7 +244,6 @@ function unavailableFailure(route: LspServerRoute, error: string): LspServerFail
   return {
     code: "server-unavailable",
     message: `Pi LSP: server ${route.serverId} is unavailable for ${route.rootPath}: ${error}`,
-    rootPath: route.rootPath,
     serverId: route.serverId,
   };
 }
@@ -288,15 +283,12 @@ export class LspServerManager<TClient extends LspManagedServerClient = LspManage
       }
     }
     return {
-      enabled: this.input.settings.enabled,
       servers,
       warnings: this.input.settings.warnings,
     };
   }
 
-  /** Resolve all matching Server Definitions and nearest roots without starting clients. */
-  async routeFile(filePath: string): Promise<readonly LspServerRoute[]> {
-    if (!this.input.settings.enabled) return [];
+  private async routeFile(filePath: string): Promise<readonly LspServerRoute[]> {
     const absolutePath = resolve(this.input.cwd, normalizeLspFilePath(filePath));
     const ancestors = await readLspAncestorDirectories(absolutePath);
     const definitions = [...this.input.settings.servers.values()].map((definition) => ({
@@ -316,7 +308,7 @@ export class LspServerManager<TClient extends LspManagedServerClient = LspManage
     );
   }
 
-  /** Query every matching capable instance while retaining independent successes and failures. */
+  /** Query matching capable instances while retaining independent operational failures. */
   async runRead<T>(
     filePath: string,
     serverId: string | undefined,
@@ -332,14 +324,14 @@ export class LspServerManager<TClient extends LspManagedServerClient = LspManage
     }
 
     const outcomes = await Promise.all(
-      routes.map(async (route): Promise<LspServerSuccess<T> | LspServerFailure> => {
+      routes.map(async (route): Promise<LspServerSuccess<T> | LspServerFailure | undefined> => {
         const resolution = await this.ensureClient(route);
         if (resolution.kind === "failure") return resolution.failure;
         if (!isCapable(resolution.instance.client)) {
+          if (serverId === undefined) return undefined;
           return {
             code: "no-capable-server",
             message: `Pi LSP: server ${route.serverId} does not support the requested operation`,
-            rootPath: route.rootPath,
             serverId: route.serverId,
           };
         }
@@ -353,7 +345,6 @@ export class LspServerManager<TClient extends LspManagedServerClient = LspManage
           return {
             code: "request-failed",
             message: `Pi LSP: server ${route.serverId} request failed: ${describeLspError(error)}`,
-            rootPath: route.rootPath,
             serverId: route.serverId,
           };
         }
@@ -363,9 +354,17 @@ export class LspServerManager<TClient extends LspManagedServerClient = LspManage
     const failures: LspServerFailure[] = [];
     const successes: LspServerSuccess<T>[] = [];
     for (const outcome of outcomes) {
+      if (outcome === undefined) continue;
       if ("code" in outcome) failures.push(outcome);
       else successes.push(outcome);
     }
+    if (failures.length === 0 && successes.length === 0) {
+      failures.push({
+        code: "no-capable-server",
+        message: "Pi LSP: no matching server supports the requested read operation",
+        serverId: "*",
+      });
+    }
     return { failures, successes };
   }
 

package/src/lsp-session-files.ts

@@ -1,9 +1,6 @@
 import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-/** The maximum retained byte length for one language server's stderr log. */
-export const MAX_SERVER_STDERR_BYTES = 1024 * 1024;
-
 /** Owns private Result Spill and bounded stderr files for one Pi session. */
 export interface LspSessionFiles {
   /** Private directory removed when the Pi session shuts down. */
@@ -12,15 +9,12 @@ export interface LspSessionFiles {
   writeResultSpill(output: string): Promise<string>;
   /** Create or return the bounded stderr file path for one language server. */
   getServerStderrPath(serverId: string): Promise<string>;
-  /** Retain the latest one megabyte of one language server's stderr stream. */
-  appendServerStderr(serverId: string, chunk: Uint8Array): Promise<string>;
   /** Remove all session files after queued writes finish. */
   close(): Promise<void>;
 }
 
 interface ServerStderrFile {
   readonly path: string;
-  content: Buffer;
 }
 
 class LspSessionFileStore implements LspSessionFiles {
@@ -45,22 +39,7 @@ class LspSessionFileStore implements LspSessionFiles {
   getServerStderrPath(serverId: string): Promise<string> {
     const stderrFile = this.serverStderrFile(serverId);
     return this.enqueueSessionFileWrite(async () => {
-      await writeFile(stderrFile.path, stderrFile.content, { mode: 0o600 });
-      await chmod(stderrFile.path, 0o600);
-      return stderrFile.path;
-    });
-  }
-
-  appendServerStderr(serverId: string, chunk: Uint8Array): Promise<string> {
-    const stderrFile = this.serverStderrFile(serverId);
-    const copiedChunk = Buffer.from(chunk);
-    return this.enqueueSessionFileWrite(async () => {
-      const combined = Buffer.concat([stderrFile.content, copiedChunk]);
-      stderrFile.content =
-        combined.length <= MAX_SERVER_STDERR_BYTES
-          ? combined
-          : Buffer.from(combined.subarray(combined.length - MAX_SERVER_STDERR_BYTES));
-      await writeFile(stderrFile.path, stderrFile.content, { mode: 0o600 });
+      await writeFile(stderrFile.path, "", { mode: 0o600 });
       await chmod(stderrFile.path, 0o600);
       return stderrFile.path;
     });
@@ -81,7 +60,6 @@ class LspSessionFileStore implements LspSessionFiles {
     if (existing !== undefined) return existing;
     const stderrFile = {
       path: join(this.directoryPath, `server-stderr-${this.nextFileIndex++}.log`),
-      content: Buffer.alloc(0),
     };
     this.stderrFiles.set(serverId, stderrFile);
     return stderrFile;

package/src/lsp-tool-contract.ts

@@ -332,7 +332,6 @@ const RegularFileSnapshotSchema = Type.Object(
   {
     kind: Type.Literal("file"),
     content_base64: Type.String(),
-    hash: Type.String({ minLength: 64, maxLength: 64 }),
     mode: Type.Integer({ minimum: 0 }),
   },
   { additionalProperties: false },
@@ -345,13 +344,17 @@ const SymlinkSnapshotSchema = Type.Object(
   },
   { additionalProperties: false },
 );
-const FileSnapshotSchema = Type.Union([
+/** Canonical pre-mutation snapshot of one filesystem path used by guarded rollback. */
+export const FileSnapshotSchema = Type.Union([
   MissingFileSnapshotSchema,
   RegularFileSnapshotSchema,
   SymlinkSnapshotSchema,
 ]);
-const ExistingFileSnapshotSchema = Type.Union([RegularFileSnapshotSchema, SymlinkSnapshotSchema]);
-const WorkspaceEditOperationSchema = Type.Union([
+export const ExistingFileSnapshotSchema = Type.Union([
+  RegularFileSnapshotSchema,
+  SymlinkSnapshotSchema,
+]);
+export const WorkspaceEditOperationSchema = Type.Union([
   Type.Object(
     {
       kind: Type.Literal("modify"),
@@ -440,7 +443,6 @@ const WorkspaceEditApplyDetailsSchema = Type.Object(
     changed_paths: Type.Array(AbsolutePathSchema),
     preview_records: Type.Optional(Type.Array(LspWorkspaceEditPreviewRecordSchema)),
     state: Type.Union([Type.Literal("applied"), Type.Literal("partial_failure")]),
-    recovery_failure_paths: Type.Optional(Type.Array(AbsolutePathSchema)),
   },
   { additionalProperties: false },
 );
@@ -460,9 +462,3 @@ export type LspWorkspaceEditPreviewRecord = Static<typeof LspWorkspaceEditPrevie
 
 /** A normalized per-server outcome used when rendering an LSP read operation. */
 export type ServerOperationOutcome = Static<typeof ServerOperationOutcomeSchema>;
-
-/** A persisted Workspace Edit Preview that can be rebuilt from the active session branch. */
-export type WorkspaceEditPreviewDetails = Static<typeof WorkspaceEditPreviewDetailsSchema>;
-
-/** The result of applying one guarded Workspace Edit Preview. */
-export type WorkspaceEditApplyDetails = Static<typeof WorkspaceEditApplyDetailsSchema>;

package/src/lsp-tool-output.ts

@@ -32,6 +32,24 @@ export function formatLspToolValue(value: LSPAny): string {
   return text === undefined ? "null" : text;
 }
 
+/** Truncate model-visible text against Pi limits, spilling the complete text when truncated. */
+export async function truncateLspOutputText(
+  text: string,
+  sessionFiles: LspSessionFiles,
+  subject: string,
+): Promise<{ readonly text: string; readonly spillPath?: string }> {
+  const truncation = truncateHead(text, {
+    maxBytes: DEFAULT_MAX_BYTES,
+    maxLines: DEFAULT_MAX_LINES,
+  });
+  if (!truncation.truncated) return { text };
+  const spillPath = await sessionFiles.writeResultSpill(text);
+  return {
+    text: `${truncation.content}\n\n[Pi LSP: ${subject} truncated; complete Result Spill: ${spillPath}]`,
+    spillPath,
+  };
+}
+
 /** Validate normalized details, truncate model-visible text, and spill every complete oversized result. */
 export async function createLspToolOutput(
   text: string,
@@ -39,26 +57,20 @@ export async function createLspToolOutput(
   sessionFiles: LspSessionFiles,
 ): Promise<AgentToolResult<LspToolResultDetails>> {
   const normalizedDetails = Value.Parse(LspToolResultDetailsSchema, details);
-  const truncated = truncateHead(text, {
-    maxBytes: DEFAULT_MAX_BYTES,
-    maxLines: DEFAULT_MAX_LINES,
-  });
-  if (!truncated.truncated) {
+  const truncated = await truncateLspOutputText(text, sessionFiles, "output");
+  if (truncated.spillPath === undefined) {
     return { content: [{ type: "text", text }], details: normalizedDetails };
   }
 
-  const spillPath = await sessionFiles.writeResultSpill(text);
-  const notice = `\n\n[Pi LSP: output truncated; complete Result Spill: ${spillPath}]`;
-  const visibleText = `${truncated.content}${notice}`;
   const detailsWithSpill =
     normalizedDetails.kind === "operation"
       ? Value.Parse(LspToolResultDetailsSchema, {
           ...normalizedDetails,
-          spill_path: spillPath,
+          spill_path: truncated.spillPath,
         })
       : normalizedDetails;
   return {
-    content: [{ type: "text", text: visibleText }],
+    content: [{ type: "text", text: truncated.text }],
     details: detailsWithSpill,
   };
 }

package/src/lsp-tool-rendering.ts

@@ -16,6 +16,7 @@ import {
   type LspToolResultDetails,
   type ServerOperationOutcome,
 } from "./lsp-tool-contract.js";
+import { pluralizedCount } from "./lsp-post-edit-diagnostics-rendering.js";
 
 /** Theme operations used by Pi LSP tool transcript rendering. */
 export type LspRenderTheme = Pick<Theme, "bold" | "fg">;
@@ -139,10 +140,6 @@ function semanticLspOperationMetric(
   return pluralizedCount(count, noun);
 }
 
-function pluralizedCount(count: number, noun: string): string {
-  return `${count} ${noun}${count === 1 ? "" : "s"}`;
-}
-
 function outcomeColor(outcome: ServerOperationOutcome["outcome"]): ThemeColor {
   switch (outcome) {
     case "success":

package/src/lsp-tool.ts

@@ -1,7 +1,11 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type {
+  AgentToolResult,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 import {
@@ -227,6 +231,23 @@ async function createLspToolOutput(
   );
 }
 
+async function readOutput(
+  operation: LspToolParameters["operation"],
+  result: Promise<LspServerReadResult<LSPAny>>,
+  dependencies: LspToolDependencies,
+) {
+  const resolved = await result;
+  requireReadSuccess(resolved);
+  return createLspToolOutput(
+    formatLspToolValue({
+      results: readOperationValue(resolved),
+      warnings: resolved.failures.map(({ message }) => message),
+    }),
+    operationDetails(operation, readOperationOutcomes(resolved)),
+    dependencies,
+  );
+}
+
 function parseLspToolParameters(input: LSPAny): LspToolParameters {
   try {
     return Value.Parse(LspToolParametersSchema, input);
@@ -440,15 +461,6 @@ async function normalizeProtocolResult(
   return Object.fromEntries(entries);
 }
 
-async function requestDocumentMethod(
-  prepared: PreparedDocument,
-  method: string,
-  parameters: LSPAny,
-  signal: AbortSignal | undefined,
-): Promise<LSPAny> {
-  return prepared.client.request<LSPAny>(method, parameters, signal);
-}
-
 function supportsResolveProvider(value: LSPAny): boolean {
   return protocolRecord(value)?.resolveProvider === true;
 }
@@ -545,9 +557,7 @@ async function workspacePreviewOutput(
   serverId: string,
   edit: WorkspaceEdit,
   positionEncoding: PositionEncodingKind,
-): Promise<
-  ReturnType<typeof createLspToolOutput> extends Promise<infer TResult> ? TResult : never
-> {
+): Promise<AgentToolResult<LspToolResultDetails>> {
   const preview = await dependencies.workspaceEdits.createPreview({
     edit,
     serverId,
@@ -617,8 +627,7 @@ async function executePositionRead(
           context: { includeDeclaration: parameters.include_declaration ?? true },
         };
       }
-      let value = await requestDocumentMethod(
-        prepared,
+      let value = await prepared.client.request<LSPAny>(
         capabilityMethod,
         requestParameters,
         signal,
@@ -1015,7 +1024,6 @@ async function executeApplyPreview(
         preview_id: parameters.preview_id,
         mutation_manifest: canonicalManifest,
         changed_paths: [...cause.recoveryFailures].sort((left, right) => left.localeCompare(right)),
-        recovery_failure_paths: [...cause.recoveryFailures],
         state: "partial_failure",
       },
       dependencies,
@@ -1127,72 +1135,42 @@ export function createLspToolDefinition(
         case "type_hierarchy":
         case "supertypes":
         case "subtypes":
-        case "prepare_rename": {
-          const result = await executePositionRead(dependencies, parameters, context, signal);
-          requireReadSuccess(result);
-          return createLspToolOutput(
-            formatLspToolValue({
-              results: readOperationValue(result),
-              warnings: result.failures.map(({ message }) => message),
-            }),
-            operationDetails(parameters.operation, readOperationOutcomes(result)),
+        case "prepare_rename":
+          return readOutput(
+            parameters.operation,
+            executePositionRead(dependencies, parameters, context, signal),
             dependencies,
           );
-        }
         case "diagnostics":
         case "document_symbols":
         case "document_links":
         case "folding_ranges":
         case "code_lenses":
-        case "document_colors": {
-          const result = await executeFileRead(dependencies, parameters, context, signal);
-          requireReadSuccess(result);
-          return createLspToolOutput(
-            formatLspToolValue({
-              results: readOperationValue(result),
-              warnings: result.failures.map(({ message }) => message),
-            }),
-            operationDetails(parameters.operation, readOperationOutcomes(result)),
+        case "document_colors":
+          return readOutput(
+            parameters.operation,
+            executeFileRead(dependencies, parameters, context, signal),
             dependencies,
           );
-        }
         case "workspace_diagnostics":
-        case "workspace_symbols": {
-          const result = await executeWorkspaceRead(dependencies, parameters, context, signal);
-          requireReadSuccess(result);
-          return createLspToolOutput(
-            formatLspToolValue({
-              results: readOperationValue(result),
-              warnings: result.failures.map(({ message }) => message),
-            }),
-            operationDetails(parameters.operation, readOperationOutcomes(result)),
+        case "workspace_symbols":
+          return readOutput(
+            parameters.operation,
+            executeWorkspaceRead(dependencies, parameters, context, signal),
             dependencies,
           );
-        }
-        case "selection_ranges": {
-          const result = await executeSelectionRanges(dependencies, parameters, context, signal);
-          requireReadSuccess(result);
-          return createLspToolOutput(
-            formatLspToolValue({
-              results: readOperationValue(result),
-              warnings: result.failures.map(({ message }) => message),
-            }),
-            operationDetails(parameters.operation, readOperationOutcomes(result)),
+        case "selection_ranges":
+          return readOutput(
+            parameters.operation,
+            executeSelectionRanges(dependencies, parameters, context, signal),
             dependencies,
           );
-        }
-        case "inlay_hints": {
-          const result = await executeInlayHints(dependencies, parameters, context, signal);
-          requireReadSuccess(result);
-          return createLspToolOutput(
-            formatLspToolValue({
-              results: readOperationValue(result),
-              warnings: result.failures.map(({ message }) => message),
-            }),
-            operationDetails(parameters.operation, readOperationOutcomes(result)),
+        case "inlay_hints":
+          return readOutput(
+            parameters.operation,
+            executeInlayHints(dependencies, parameters, context, signal),
             dependencies,
           );
-        }
         case "format_document":
         case "format_range":
         case "format_on_type":

package/src/lsp-workspace-edit.ts

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import {
   chmod,
   lstat,
@@ -27,6 +27,12 @@ import {
   convertLspProtocolPosition,
   normalizeLspPositionEncoding,
 } from "./lsp-position-encoding.js";
+import {
+  FileSnapshotSchema,
+  LspWorkspaceEditPreviewRecordSchema,
+  WorkspaceEditOperationSchema,
+} from "./lsp-tool-contract.js";
+import type { Static } from "typebox";
 
 const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf]);
 const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
@@ -48,63 +54,19 @@ export interface LspMutationManifest {
   readonly entries: readonly LspMutationManifestEntry[];
 }
 
-type FileSnapshot =
-  | { readonly kind: "missing" }
-  | {
-      readonly kind: "file";
-      readonly content_base64: string;
-      readonly hash: string;
-      readonly mode: number;
-    }
-  | { readonly kind: "symlink"; readonly link_target: string; readonly mode: number };
-
-type ModifyOperation = {
-  readonly kind: "modify";
-  readonly named_path: string;
-  readonly path: string;
-  readonly named_before: FileSnapshot;
-  readonly before: FileSnapshot;
-  after_base64: string;
-  readonly mode: number;
-};
+/** Canonical pre-mutation snapshot of one filesystem path used by guarded rollback. */
+type FileSnapshot = Static<typeof FileSnapshotSchema>;
 
-type CreateOperation = {
-  readonly kind: "create";
-  readonly named_path: string;
-  readonly before: FileSnapshot;
-  after_base64: string;
-  readonly mode: number;
-};
+/** Schema-derived operation with a writable `after_base64` for incremental document edits. */
+type Writable<T> = { -readonly [K in keyof T]: T[K] };
+type EditableOperation = Writable<
+  Extract<Static<typeof WorkspaceEditOperationSchema>, { kind: "modify" | "create" }>
+>;
 
-type DeleteOperation = {
-  readonly kind: "delete";
-  readonly named_path: string;
-  readonly before: Exclude<FileSnapshot, { readonly kind: "missing" }>;
-};
-
-type RenameOperation = {
-  readonly kind: "rename";
-  readonly named_path: string;
-  readonly destination_path: string;
-  readonly before: Exclude<FileSnapshot, { readonly kind: "missing" }>;
-  readonly destination_before: FileSnapshot;
-};
-
-type NormalizedWorkspaceOperation =
-  | ModifyOperation
-  | CreateOperation
-  | DeleteOperation
-  | RenameOperation;
+type NormalizedWorkspaceOperation = Static<typeof WorkspaceEditOperationSchema>;
 
 /** Schema-friendly preview record persisted in LSP tool result details. */
-export interface LspWorkspaceEditPreview {
-  readonly kind: "workspace_edit_preview";
-  readonly preview_id: string;
-  readonly server_id: string;
-  readonly summary: string;
-  readonly state: "available" | "applied";
-  readonly operations: readonly NormalizedWorkspaceOperation[];
-}
+type LspWorkspaceEditPreview = Static<typeof LspWorkspaceEditPreviewRecordSchema>;
 
 /** Result of one guarded Workspace Edit application. */
 export interface LspWorkspaceEditApplyResult {
@@ -164,8 +126,6 @@ type WorkspaceEditErrorCode =
 
 /** Expected preview normalization, validation, apply, or rollback failure. */
 export class LspWorkspaceEditError extends Error {
-  readonly _tag = "LspWorkspaceEditError" as const;
-
   /** Construct a stable Workspace Edit failure with optional unrecovered paths. */
   constructor(
     readonly code: WorkspaceEditErrorCode,
@@ -194,16 +154,6 @@ interface DecodedUtf8Document {
   readonly text: string;
 }
 
-/** Counts accepted and rejected persisted Workspace Edit Preview records. */
-export interface LspWorkspaceEditReplayResult {
-  readonly accepted: number;
-  readonly rejected: number;
-}
-
-function hashContents(contents: Buffer): string {
-  return createHash("sha256").update(contents).digest("hex");
-}
-
 function contentsFromSnapshot(snapshot: FileSnapshot): Buffer {
   if (snapshot.kind !== "file") {
     throw new LspWorkspaceEditError("invalid_destination", "expected a regular file");
@@ -236,7 +186,6 @@ async function snapshotNamedPath(path: string): Promise<FileSnapshot> {
   return {
     kind: "file",
     content_base64: contents.toString("base64"),
-    hash: hashContents(contents),
     mode,
   };
 }
@@ -424,10 +373,6 @@ async function restorePath(
   await symlink(snapshot.link_target, path);
 }
 
-function mutablePreview(preview: LspWorkspaceEditPreview): LspWorkspaceEditPreview {
-  return structuredClone(preview);
-}
-
 /** Own persisted Workspace Edit Preview state and guarded one-use application. */
 export class LspWorkspaceEditStore {
   private readonly previews = new Map<string, LspWorkspaceEditPreview>();
@@ -446,7 +391,7 @@ export class LspWorkspaceEditStore {
   /** Normalize and persist one language-server Workspace Edit without mutating files. */
   async createPreview(input: CreateWorkspaceEditPreviewInput): Promise<LspWorkspaceEditPreview> {
     const operations: NormalizedWorkspaceOperation[] = [];
-    const editableOperations = new Map<string, ModifyOperation | CreateOperation>();
+    const editableOperations = new Map<string, EditableOperation>();
     const resourceActions = new Map<string, string>();
     const destinations = new Set<string>();
     const encoding = input.positionEncoding ?? "utf-16";
@@ -500,7 +445,7 @@ export class LspWorkspaceEditStore {
       const current = contentsFromSnapshot(before);
       const decoded = decodeUtf8(current, targetPath);
       const after = encodeUtf8(applyTextEdits(decoded.text, edits, encoding), decoded.bom);
-      const operation: ModifyOperation = {
+      const operation: EditableOperation = {
         kind: "modify",
         named_path: namedPath,
         path: targetPath,
@@ -540,7 +485,7 @@ export class LspWorkspaceEditStore {
             `create destination exists: ${path}`,
           );
         }
-        const operation: CreateOperation = {
+        const operation: EditableOperation = {
           kind: "create",
           named_path: path,
           before,
@@ -649,18 +594,16 @@ export class LspWorkspaceEditStore {
   }
 
   /** Rebuild branch-local available/applied preview state from persisted tool result records. */
-  replayPreviewRecords(records: readonly LSPAny[]): LspWorkspaceEditReplayResult {
-    let accepted = 0;
+  replayPreviewRecords(records: readonly LSPAny[]): number {
     let rejected = 0;
     for (const record of records) {
       if (!isWorkspaceEditPreview(record)) {
         rejected++;
         continue;
       }
-      this.previews.set(record.preview_id, mutablePreview(record));
-      accepted++;
+      this.previews.set(record.preview_id, structuredClone(record));
     }
-    return { accepted, rejected };
+    return rejected;
   }
 
   /** Revalidate and apply one preview inside every sorted canonical mutation queue. */

package/src/pi-lsp-extension.ts

@@ -1,11 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import {
-  DEFAULT_MAX_BYTES,
-  DEFAULT_MAX_LINES,
   getAgentDir,
   SettingsManager,
-  truncateHead,
   type ExtensionAPI,
   type ExtensionContext,
   type ExtensionFactory,
@@ -20,11 +17,10 @@ import {
   type Diagnostic,
 } from "vscode-languageserver-protocol/node";
 import {
-  appendPiPostEditDiagnostics,
+  appendPostEditDiagnostics,
   type PostEditDiagnosticOutcome,
   type PostEditDiagnosticPath,
   type PostEditDiagnosticsResultPatch,
-  type PostEditDiagnosticsRunner,
 } from "./lsp-post-edit-diagnostics.js";
 import {
   createPostEditDiagnosticsEntryData,
@@ -45,6 +41,7 @@ import {
   type LspWorkspaceEditPreviewRecord,
 } from "./lsp-tool-contract.js";
 import { registerLspTool } from "./lsp-tool.js";
+import { truncateLspOutputText } from "./lsp-tool-output.js";
 import { LspWorkspaceEditStore } from "./lsp-workspace-edit.js";
 import { resolveLspSettings } from "./pi-lsp-settings.js";
 
@@ -143,13 +140,13 @@ function failureDiagnosticOutcome(
   return { kind: "unavailable_server", path, serverId: failure.serverId };
 }
 
-class ManagerPostEditDiagnosticsRunner implements PostEditDiagnosticsRunner {
+class ManagerPostEditDiagnosticsRunner {
   constructor(
     private readonly session: ActivePiLspSession,
     private readonly signal: AbortSignal | undefined,
   ) {}
 
-  async runPostEditDiagnostics(
+  async run(
     paths: readonly PostEditDiagnosticPath[],
   ): Promise<readonly PostEditDiagnosticOutcome[]> {
     const outcomes: PostEditDiagnosticOutcome[] = [];
@@ -207,24 +204,20 @@ async function appendSessionPostEditDiagnostics(
   session: ActivePiLspSession,
   context: ExtensionContext,
 ): Promise<PostEditDiagnosticsResultPatch | undefined> {
-  const patch = await appendPiPostEditDiagnostics(
-    event,
-    new ManagerPostEditDiagnosticsRunner(session, context.signal),
+  const patch = await appendPostEditDiagnostics(event, (paths) =>
+    new ManagerPostEditDiagnosticsRunner(session, context.signal).run(paths),
   );
   if (patch === undefined) return undefined;
   const appendedValue = patch.content.at(-1);
   if (!Value.Check(AppendedTextContentSchema, appendedValue)) return undefined;
   let appended: Static<typeof AppendedTextContentSchema> = appendedValue;
-  const truncation = truncateHead(appended.text, {
-    maxBytes: DEFAULT_MAX_BYTES,
-    maxLines: DEFAULT_MAX_LINES,
-  });
-  if (truncation.truncated) {
-    const spillPath = await session.sessionFiles.writeResultSpill(appended.text);
-    appended = {
-      type: "text",
-      text: `${truncation.content}\n\n[Pi LSP: diagnostics truncated; complete Result Spill: ${spillPath}]`,
-    };
+  const truncation = await truncateLspOutputText(
+    appended.text,
+    session.sessionFiles,
+    "diagnostics",
+  );
+  if (truncation.spillPath !== undefined) {
+    appended = { type: "text", text: truncation.text };
   }
   const partialApplyFailure =
     event.toolName === "lsp" &&
@@ -280,9 +273,9 @@ export class PiLspLifecycleController {
     const replay = workspaceEdits.replayPreviewRecords(
       branchLspToolResultDetails(context.sessionManager.getBranch()),
     );
-    if (replay.rejected > 0) {
+    if (replay > 0) {
       context.ui.notify(
-        `Pi LSP ignored ${replay.rejected} invalid Workspace Edit Preview record${replay.rejected === 1 ? "" : "s"} on the active session branch.`,
+        `Pi LSP ignored ${replay} invalid Workspace Edit Preview record${replay === 1 ? "" : "s"} on the active session branch.`,
         "warning",
       );
     }

package/src/pi-lsp-settings.ts

@@ -96,7 +96,6 @@ export interface LspTimeouts {
 
 /** Reports resolved trusted configuration, retaining valid entries when other settings are invalid. */
 export interface ResolvedLspSettings {
-  readonly enabled: boolean;
   readonly servers: ReadonlyMap<string, LspServerDefinition>;
   readonly timeouts: LspTimeouts;
   readonly warnings: readonly string[];
@@ -337,7 +336,6 @@ export function resolveLspSettings(reader: LspSettingsReader): ResolvedLspSettin
   const globalLayer = readLspLayer(reader.getGlobalSettings(), "global");
   const projectLayer = readLspLayer(reader.getProjectSettings(), "project");
   return {
-    enabled: true,
     servers: mergeLspServers(globalLayer, projectLayer),
     timeouts: mergeLspTimeouts(globalLayer, projectLayer),
     warnings: [...globalLayer.warnings, ...projectLayer.warnings],