@trim21/personal-pi-extensions 0.0.313 → 0.0.315

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.313",
+  "version": "0.0.315",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/aft/tools.ts

@@ -120,15 +120,6 @@ export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void
         content: [{ type: "text", text }],
         details: {
           truncated,
-          pendant: {
-            markdown: buildPendantMarkdown({
-              title: "aft_outline",
-              input: params,
-              output: text,
-              truncated,
-            }),
-            expanded: true,
-          } satisfies ToolPendant,
         },
       };
     },

package/src/claude-code/files.ts

@@ -15,6 +15,7 @@ import {
 import { Type } from "typebox";
 
 import { createLspService, initLsp, type LspService } from "../lib/lsp/lsp.js";
+import { type ToolPendant } from "../lib/pendant.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import {
   type ClaudeCodeState,
@@ -45,6 +46,43 @@ function formatFileSize(bytes: number): string {
   return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
 }
 
+/** Edit/Write 结果的可折叠面板：diff（```diff 代码块）+ LSP errors（有则显示）。 */
+export function buildEditPendant(options: {
+  filePath: string;
+  diff: string;
+  diagnosticText: string;
+}): ToolPendant {
+  const lines = [`## Diff — \`${options.filePath}\``, "", "```diff", options.diff, "```"];
+  if (options.diagnosticText !== "") {
+    lines.push("", "## LSP errors", "", "```text", options.diagnosticText, "```");
+  }
+  return { markdown: lines.join("\n"), expanded: true };
+}
+
+/** Read 结果的可折叠面板：路径、总行数、读取范围与文件大小。 */
+export function buildReadPendant(options: {
+  filePath: string;
+  byteSize: number;
+  offset?: number;
+  limit?: number;
+  totalLines?: number;
+  type?: string;
+}): ToolPendant {
+  const lines = ["## Read", "", `- **Path**: \`${options.filePath}\``];
+  if (options.type) lines.push(`- **Type**: ${options.type}`);
+  if (options.totalLines !== undefined) {
+    const start = options.offset ?? 1;
+    const end = Math.min(
+      options.limit === undefined ? options.totalLines : start + options.limit - 1,
+      options.totalLines,
+    );
+    lines.push(`- **Total lines**: ${options.totalLines}`);
+    if (start <= end) lines.push(`- **Range**: ${start}-${end}`);
+  }
+  lines.push(`- **Size**: ${formatFileSize(options.byteSize)}`);
+  return { markdown: lines.join("\n"), expanded: false };
+}
+
 /** Tool guidance, kept in markdown so it reads like documentation. */
 const READ_PROMPT = readFileSync(fileURLToPath(new URL("read.md", import.meta.url)), "utf8").trim();
 const EDIT_PROMPT = readFileSync(fileURLToPath(new URL("edit.md", import.meta.url)), "utf8").trim();
@@ -69,6 +107,8 @@ export interface FileToolDetails {
    * session 文件，resume 后由 session_start 重建 reads state。
    */
   reads?: Record<string, FileSnapshot>;
+  /** 可折叠的 diff / LSP 结果面板（pi TUI 渲染）。 */
+  pendant?: ToolPendant;
 }
 
 function snapshotOf(content: Uint8Array | string, textEditable = true): FileSnapshot {
@@ -286,7 +326,17 @@ export function registerFileTools(
         const snapshot = snapshotOf(image, false);
         const key = await readStateKey(filePath);
         state.reads.set(key, snapshot);
-        return { content, details: { reads: { [key]: snapshot } } };
+        return {
+          content,
+          details: {
+            reads: { [key]: snapshot },
+            pendant: buildReadPendant({
+              filePath,
+              byteSize: image.length,
+              type: imageMime,
+            }),
+          },
+        };
       }
 
       const buffer = await readFile(filePath);
@@ -316,7 +366,16 @@ export function registerFileTools(
       });
       return {
         content: [{ type: "text", text: formatted.text }],
-        details: { reads: { [key]: snapshot } },
+        details: {
+          reads: { [key]: snapshot },
+          pendant: buildReadPendant({
+            filePath,
+            byteSize: buffer.length,
+            offset: params.offset ?? 1,
+            limit: params.limit,
+            totalLines: formatted.totalLines,
+          }),
+        },
       };
     },
   });
@@ -357,127 +416,145 @@ export function registerFileTools(
           replaceAll: params.replace_all,
         },
       });
-      const [message, details] = await withFileMutationQueue<[string, FileToolDetails]>(
-        filePath,
-        async () => {
-          const oldString = params.old_string;
-          const newString = params.new_string;
-          if (oldString === newString) {
-            throw new Error("No changes to make: old_string and new_string are exactly the same.");
-          }
-          // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
-          if (oldString === "") {
-            let exists = true;
-            try {
-              const value = await stat(filePath);
-              if (value.isFile()) {
-                const content = await readFile(filePath, "utf8");
-                if (content.trim() !== "") {
-                  throw new Error("Cannot create new file - file already exists.");
-                }
-              }
-            } catch (error) {
-              if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-                exists = false;
-              } else {
-                throw error;
-              }
-            }
-            if (!exists) await mkdir(dirname(filePath), { recursive: true });
-            await writeFile(filePath, newString, "utf8");
-            const snapshot = snapshotOf(newString);
-            const key = await readStateKey(filePath);
-            state.reads.set(key, snapshot);
-            return [
-              `The file ${filePath} has been updated successfully.`,
-              { reads: { [key]: snapshot } },
-            ];
-          }
-          const replaceAll = params.replace_all ?? false;
-          // 防止 OOM 的大文件检查（对齐 Claude Code）
+      const [message, details, diagnosticText] = await withFileMutationQueue<
+        [string, FileToolDetails, string]
+      >(filePath, async () => {
+        const oldString = params.old_string;
+        const newString = params.new_string;
+        if (oldString === newString) {
+          throw new Error("No changes to make: old_string and new_string are exactly the same.");
+        }
+        // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
+        if (oldString === "") {
+          let exists = true;
           try {
-            const { size } = await stat(filePath);
-            if (size > MAX_EDIT_FILE_SIZE) {
-              throw new Error(
-                `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
-              );
-            }
-          } catch (error) {
-            if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-              throw error;
+            const value = await stat(filePath);
+            if (value.isFile()) {
+              const content = await readFile(filePath, "utf8");
+              if (content.trim() !== "") {
+                throw new Error("Cannot create new file - file already exists.");
+              }
             }
-          }
-          let content: Buffer;
-          try {
-            content = await readFile(filePath);
           } catch (error) {
             if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-              const suggestion = await didYouMean(filePath, ctx.cwd);
-              throw new Error(
-                `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
-                { cause: error },
-              );
+              exists = false;
+            } else {
+              throw error;
             }
-            throw error;
-          }
-          if (extname(filePath).toLowerCase() === ".ipynb") {
-            throw new Error(
-              "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
-            );
           }
+          if (!exists) await mkdir(dirname(filePath), { recursive: true });
+          await writeFile(filePath, newString, "utf8");
+          const snapshot = snapshotOf(newString);
           const key = await readStateKey(filePath);
-          requireCurrentRead(state, key, filePath, content);
-          await access(filePath, constants.R_OK | constants.W_OK);
-          throwIfAborted(signal);
-          const original = content.toString("utf8");
-
-          // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
-          const crlfCount = (original.match(/\r\n/g) ?? []).length;
-          const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
-          const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
-          const normalized = original.replaceAll("\r\n", "\n");
-          const actualOldString = findActualString(normalized, oldString) ?? oldString;
-          const matches = normalized.split(actualOldString).length - 1;
-          if (matches === 0) {
-            throw new Error(`String to replace not found in file.\nString: ${oldString}`);
-          }
-          if (!replaceAll && matches > 1) {
-            throw new Error(
-              `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
-            );
-          }
-          const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
-          // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
-          const updated = replaceAll
-            ? normalized.split(actualOldString).join(actualNewString)
-            : normalized.replace(actualOldString, () => actualNewString);
-          const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
-          await writeFile(filePath, restored, "utf8");
-          const snapshot = snapshotOf(restored);
           state.reads.set(key, snapshot);
-          const diff = generateDiffString(original, restored);
-          const text = replaceAll
-            ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
-            : `The file ${filePath} has been updated successfully.`;
+          const diff = generateDiffString("", newString);
+          throwIfAborted(signal);
+          const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
           return [
-            text,
+            `The file ${filePath} has been updated successfully.`,
             {
               diff: diff.diff,
-              patch: generateUnifiedPatch(filePath, original, restored),
+              patch: generateUnifiedPatch(filePath, "", newString),
               firstChangedLine: diff.firstChangedLine,
               reads: { [key]: snapshot },
             },
+            diagnosticText,
           ];
-        },
-      );
+        }
+        const replaceAll = params.replace_all ?? false;
+        // 防止 OOM 的大文件检查（对齐 Claude Code）
+        try {
+          const { size } = await stat(filePath);
+          if (size > MAX_EDIT_FILE_SIZE) {
+            throw new Error(
+              `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
+            );
+          }
+        } catch (error) {
+          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+          }
+        }
+        let content: Buffer;
+        try {
+          content = await readFile(filePath);
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            const suggestion = await didYouMean(filePath, ctx.cwd);
+            throw new Error(
+              `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+              { cause: error },
+            );
+          }
+          throw error;
+        }
+        if (extname(filePath).toLowerCase() === ".ipynb") {
+          throw new Error(
+            "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
+          );
+        }
+        const key = await readStateKey(filePath);
+        requireCurrentRead(state, key, filePath, content);
+        await access(filePath, constants.R_OK | constants.W_OK);
+        throwIfAborted(signal);
+        const original = content.toString("utf8");
+
+        // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
+        const crlfCount = (original.match(/\r\n/g) ?? []).length;
+        const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
+        const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
+        const normalized = original.replaceAll("\r\n", "\n");
+        const actualOldString = findActualString(normalized, oldString) ?? oldString;
+        const matches = normalized.split(actualOldString).length - 1;
+        if (matches === 0) {
+          throw new Error(`String to replace not found in file.\nString: ${oldString}`);
+        }
+        if (!replaceAll && matches > 1) {
+          throw new Error(
+            `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
+          );
+        }
+        const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
+        // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
+        const updated = replaceAll
+          ? normalized.split(actualOldString).join(actualNewString)
+          : normalized.replace(actualOldString, () => actualNewString);
+        const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
+        await writeFile(filePath, restored, "utf8");
+        const snapshot = snapshotOf(restored);
+        state.reads.set(key, snapshot);
+        const diff = generateDiffString(original, restored);
+        const text = replaceAll
+          ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
+          : `The file ${filePath} has been updated successfully.`;
+        throwIfAborted(signal);
+        const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+        return [
+          text,
+          {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original, restored),
+            firstChangedLine: diff.firstChangedLine,
+            reads: { [key]: snapshot },
+          },
+          diagnosticText,
+        ];
+      });
 
-      throwIfAborted(signal);
-      // 写后等待文档诊断，ERROR 级错误追加到输出让模型可见
-      const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
       const text = diagnosticText
         ? `${message}\n\nLSP errors detected in this file, please fix:\n${diagnosticText}`
         : message;
-      return { content: [{ type: "text" as const, text }], details };
+      return {
+        content: [{ type: "text" as const, text }],
+        details: {
+          ...details,
+          pendant: buildEditPendant({
+            filePath,
+            diff: details.diff ?? "",
+            diagnosticText,
+          }),
+        },
+      };
     },
   });
 
@@ -508,55 +585,64 @@ export function registerFileTools(
         absolutePath: filePath,
         change: { oldText: "", newText: params.content },
       });
-      const [message, details] = await withFileMutationQueue<[string, FileToolDetails]>(
-        filePath,
-        async () => {
-          let original: string | undefined;
-          let key: string | undefined;
-          try {
-            const value = await stat(filePath);
-            if (value.isFile()) {
-              const content = await readFile(filePath);
-              key = await readStateKey(filePath);
-              requireCurrentRead(state, key, filePath, content);
-              original = content.toString("utf8");
-            }
-          } catch (error) {
-            if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-              throw error;
-            }
+      const [message, details, diagnosticText] = await withFileMutationQueue<
+        [string, FileToolDetails, string]
+      >(filePath, async () => {
+        let original: string | undefined;
+        let key: string | undefined;
+        try {
+          const value = await stat(filePath);
+          if (value.isFile()) {
+            const content = await readFile(filePath);
+            key = await readStateKey(filePath);
+            requireCurrentRead(state, key, filePath, content);
+            original = content.toString("utf8");
           }
-          throwIfAborted(signal);
-          await mkdir(dirname(filePath), { recursive: true });
-          await writeFile(filePath, params.content, "utf8");
-          const snapshot = snapshotOf(params.content);
-          // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
-          const resolvedKey = key ?? (await readStateKey(filePath));
-          state.reads.set(resolvedKey, snapshot);
-          const diff = generateDiffString(original ?? "", params.content);
-          const text =
-            original === undefined
-              ? `File created successfully at: ${filePath}`
-              : `The file ${filePath} has been updated successfully.`;
-          return [
-            text,
-            {
-              diff: diff.diff,
-              patch: generateUnifiedPatch(filePath, original ?? "", params.content),
-              firstChangedLine: diff.firstChangedLine,
-              reads: { [resolvedKey]: snapshot },
-            },
-          ];
-        },
-      );
+        } catch (error) {
+          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+          }
+        }
+        throwIfAborted(signal);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, params.content, "utf8");
+        const snapshot = snapshotOf(params.content);
+        // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
+        const resolvedKey = key ?? (await readStateKey(filePath));
+        state.reads.set(resolvedKey, snapshot);
+        const diff = generateDiffString(original ?? "", params.content);
+        const text =
+          original === undefined
+            ? `File created successfully at: ${filePath}`
+            : `The file ${filePath} has been updated successfully.`;
+        throwIfAborted(signal);
+        const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+        return [
+          text,
+          {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original ?? "", params.content),
+            firstChangedLine: diff.firstChangedLine,
+            reads: { [resolvedKey]: snapshot },
+          },
+          diagnosticText,
+        ];
+      });
 
-      throwIfAborted(signal);
-      // 写后等待文档诊断，ERROR 级错误追加到输出让模型可见
-      const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
       const text = diagnosticText
         ? `${message}\n\nLSP errors detected in this file, please fix:\n${diagnosticText}`
         : message;
-      return { content: [{ type: "text" as const, text }], details };
+      return {
+        content: [{ type: "text" as const, text }],
+        details: {
+          ...details,
+          pendant: buildEditPendant({
+            filePath,
+            diff: details.diff ?? "",
+            diagnosticText,
+          }),
+        },
+      };
     },
   });
 }

package/src/opencode/files.ts

@@ -506,79 +506,84 @@ function registerEditTool(pi: ExtensionAPI, service: LspService): void {
         if (signal?.aborted) throw new Error("Operation aborted");
       };
 
-      const [message, details] = await withFileMutationQueue(absolutePath, async () => {
-        throwIfAborted();
+      const [message, details, diagnosticText] = await withFileMutationQueue(
+        absolutePath,
+        async () => {
+          throwIfAborted();
 
-        // opencode: 前置校验，先于空 oldString 分支
-        if (oldString === newString) {
-          throw new Error("No changes to apply: oldString and newString are identical.");
-        }
+          // opencode: 前置校验，先于空 oldString 分支
+          if (oldString === newString) {
+            throw new Error("No changes to apply: oldString and newString are identical.");
+          }
+
+          // opencode: 空 oldString + 文件不存在 → 创建新文件；文件存在 → 报错
+          if (oldString === "") {
+            let exists = true;
+            try {
+              await access(absolutePath, constants.F_OK);
+            } catch {
+              exists = false;
+            }
+            throwIfAborted();
+            if (exists) {
+              throw new Error(
+                "oldString cannot be empty when editing an existing file. Provide the exact text to replace, or use write for an intentional full-file replacement.",
+              );
+            }
+            // opencode: writeWithDirs 自动创建父目录；newString 开头的 BOM 原样保留
+            await mkdir(dirname(absolutePath), { recursive: true });
+            throwIfAborted();
+            await writeFile(absolutePath, newString, "utf8");
+            throwIfAborted();
+            const diagnosticText = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd);
+            return [
+              "Edit applied successfully.",
+              { diff: "", patch: "", firstChangedLine: 0 },
+              diagnosticText,
+            ] as const;
+          }
 
-        // opencode: 空 oldString + 文件不存在 → 创建新文件；文件存在 → 报错
-        if (oldString === "") {
-          let exists = true;
           try {
-            await access(absolutePath, constants.F_OK);
-          } catch {
-            exists = false;
+            await access(absolutePath, constants.R_OK | constants.W_OK);
+          } catch (error: unknown) {
+            throwIfAborted();
+            const msg =
+              error instanceof Error && "code" in error && typeof error.code === "string"
+                ? `Error code: ${error.code}`
+                : String(error);
+            throw new Error(`Could not edit file: ${filePath}. ${msg}.`, { cause: error });
           }
           throwIfAborted();
-          if (exists) {
-            throw new Error(
-              "oldString cannot be empty when editing an existing file. Provide the exact text to replace, or use write for an intentional full-file replacement.",
-            );
-          }
-          // opencode: writeWithDirs 自动创建父目录；newString 开头的 BOM 原样保留
-          await mkdir(dirname(absolutePath), { recursive: true });
+
+          const buffer = await readFile(absolutePath);
+          const rawContent = buffer.toString("utf8");
           throwIfAborted();
-          await writeFile(absolutePath, newString, "utf8");
+
+          // Strip BOM then normalize line endings to LF.
+          // The opencode replacers split on \n and expect only LF.
+          const { bom, text: content } = stripBom(rawContent);
+          const originalEnding = detectLineEnding(content);
+          const normalizedContent = normalizeToLF(content);
+
+          const newContent = replace(normalizedContent, oldString, newString, replaceAll);
           throwIfAborted();
-          return [
-            "Edit applied successfully.",
-            { diff: "", patch: "", firstChangedLine: 0 },
-          ] as const;
-        }
 
-        try {
-          await access(absolutePath, constants.R_OK | constants.W_OK);
-        } catch (error: unknown) {
+          const finalContent = bom + restoreLineEndings(newContent, originalEnding);
+          await writeFile(absolutePath, finalContent, "utf8");
           throwIfAborted();
-          const msg =
-            error instanceof Error && "code" in error && typeof error.code === "string"
-              ? `Error code: ${error.code}`
-              : String(error);
-          throw new Error(`Could not edit file: ${filePath}. ${msg}.`, { cause: error });
-        }
-        throwIfAborted();
 
-        const buffer = await readFile(absolutePath);
-        const rawContent = buffer.toString("utf8");
-        throwIfAborted();
-
-        // Strip BOM then normalize line endings to LF.
-        // The opencode replacers split on \n and expect only LF.
-        const { bom, text: content } = stripBom(rawContent);
-        const originalEnding = detectLineEnding(content);
-        const normalizedContent = normalizeToLF(content);
-
-        const newContent = replace(normalizedContent, oldString, newString, replaceAll);
-        throwIfAborted();
-
-        const finalContent = bom + restoreLineEndings(newContent, originalEnding);
-        await writeFile(absolutePath, finalContent, "utf8");
-        throwIfAborted();
-
-        const diffResult = generateDiffString(normalizedContent, newContent);
-        const patch = generateUnifiedPatch(filePath, normalizedContent, newContent);
-        return [
-          "Edit applied successfully.",
-          { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },
-        ] as const;
-      });
+          const diffResult = generateDiffString(normalizedContent, newContent);
+          const patch = generateUnifiedPatch(filePath, normalizedContent, newContent);
+          throwIfAborted();
+          const diagnosticText = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd);
+          return [
+            "Edit applied successfully.",
+            { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },
+            diagnosticText,
+          ] as const;
+        },
+      );
 
-      throwIfAborted();
-      // opencode: 写后等待文档诊断，ERROR 级错误追加到输出让模型可见
-      const diagnosticText = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd);
       const text = diagnosticText
         ? `${message}\n\nLSP errors detected in this file, please fix:\n${diagnosticText}`
         : message;
@@ -639,38 +644,39 @@ function registerWriteTool(pi: ExtensionAPI, service: LspService): void {
         if (signal?.aborted) throw new Error("Operation aborted");
       };
 
-      const [message, details] = await withFileMutationQueue(absolutePath, async () => {
-        throwIfAborted();
+      const [message, details, diagnosticText] = await withFileMutationQueue(
+        absolutePath,
+        async () => {
+          throwIfAborted();
 
-        // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
-        // 否则用新内容自带的 BOM
-        let existing: Buffer | undefined;
-        try {
-          const fh = await open(absolutePath, "r");
+          // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
+          // 否则用新内容自带的 BOM
+          let existing: Buffer | undefined;
           try {
-            existing = Buffer.alloc(3);
-            const { bytesRead } = await fh.read(existing, 0, 3, 0);
-            if (bytesRead < 3) existing = undefined;
-          } finally {
-            await fh.close();
+            const fh = await open(absolutePath, "r");
+            try {
+              existing = Buffer.alloc(3);
+              const { bytesRead } = await fh.read(existing, 0, 3, 0);
+              if (bytesRead < 3) existing = undefined;
+            } finally {
+              await fh.close();
+            }
+          } catch {
+            // 文件不存在：无旧 BOM
           }
-        } catch {
-          // 文件不存在：无旧 BOM
-        }
-        throwIfAborted();
-        const { bom: desiredBom, text: nextText } = resolveBom(existing, content);
+          throwIfAborted();
+          const { bom: desiredBom, text: nextText } = resolveBom(existing, content);
 
-        await mkdir(dir, { recursive: true });
-        throwIfAborted();
-        await writeFile(absolutePath, desiredBom + nextText, "utf8");
-        throwIfAborted();
+          await mkdir(dir, { recursive: true });
+          throwIfAborted();
+          await writeFile(absolutePath, desiredBom + nextText, "utf8");
+          throwIfAborted();
+          const diagnosticText = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd);
 
-        return ["Wrote file successfully.", undefined] as const;
-      });
+          return ["Wrote file successfully.", undefined, diagnosticText] as const;
+        },
+      );
 
-      throwIfAborted();
-      // opencode: 写后等待文档诊断，ERROR 级错误追加到输出让模型可见
-      const diagnosticText = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd);
       const text = diagnosticText
         ? `${message}\n\nLSP errors detected in this file, please fix:\n${diagnosticText}`
         : message;