@trim21/personal-pi-extensions 0.0.270 → 0.0.272

package/package.json

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

package/src/claude-code/files.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { constants, readFileSync } from "node:fs";
-import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, extname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -164,17 +164,44 @@ export function exactReplace(
   return content.slice(0, index) + newString + content.slice(index + oldString.length);
 }
 
-async function requireCurrentRead(state: ClaudeCodeState, filePath: string): Promise<void> {
-  const readSnapshot = state.reads.get(filePath);
+/**
+ * reads 记账 key：解析 symlink 后的真实路径，与 withFileMutationQueue 的队列
+ * key 对齐。文件尚不存在（Write 新建 / Edit 空 old_string 创建）时 realpath
+ * 抛 ENOENT，回退到已规范化路径。
+ */
+async function readStateKey(filePath: string): Promise<string> {
+  try {
+    return await realpath(filePath);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return filePath;
+    }
+    throw error;
+  }
+}
+
+/**
+ * 校验「已读且未变」。key 与 currentContent 由调用方提供：调用方每次工具调用
+ * 只 realpath / readFile 一次，避免重复 IO。
+ */
+function requireCurrentRead(
+  state: ClaudeCodeState,
+  key: string,
+  filePath: string,
+  currentContent: Uint8Array,
+): void {
+  const readSnapshot = state.reads.get(key);
   if (!readSnapshot) {
     throw new Error("File has not been read yet. Read it first before writing to it.");
   }
   if (!readSnapshot.textEditable) {
     throw new Error(`Cannot edit or overwrite a binary file with a text tool: ${filePath}`);
   }
-  const currentContent = await readFile(filePath);
-  const current = snapshotOf(currentContent);
-  if (!snapshotsEqual(readSnapshot, current)) {
+  if (!snapshotsEqual(readSnapshot, snapshotOf(currentContent))) {
     throw new Error(
       "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.",
     );
@@ -249,8 +276,9 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
           { type: "image", data, mimeType: imageMime },
         ];
         const snapshot = snapshotOf(image, false);
-        state.reads.set(filePath, snapshot);
-        return { content, details: { reads: { [filePath]: snapshot } } };
+        const key = await readStateKey(filePath);
+        state.reads.set(key, snapshot);
+        return { content, details: { reads: { [key]: snapshot } } };
       }
 
       const buffer = await readFile(filePath);
@@ -272,10 +300,11 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         );
       }
       const snapshot = snapshotOf(buffer);
-      state.reads.set(filePath, snapshot);
+      const key = await readStateKey(filePath);
+      state.reads.set(key, snapshot);
       return {
         content: [{ type: "text", text: formatted.text }],
-        details: { reads: { [filePath]: snapshot } },
+        details: { reads: { [key]: snapshot } },
       };
     },
   });
@@ -343,12 +372,13 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
           if (!exists) await mkdir(dirname(filePath), { recursive: true });
           await writeFile(filePath, newString, "utf8");
           const snapshot = snapshotOf(newString);
-          state.reads.set(filePath, snapshot);
+          const key = await readStateKey(filePath);
+          state.reads.set(key, snapshot);
           return {
             content: [
               { type: "text", text: `The file ${filePath} has been updated successfully.` },
             ],
-            details: { reads: { [filePath]: snapshot } } satisfies FileToolDetails,
+            details: { reads: { [key]: snapshot } } satisfies FileToolDetails,
           };
         }
         const replaceAll = params.replace_all ?? false;
@@ -365,9 +395,9 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             throw error;
           }
         }
-        let original: string;
+        let content: Buffer;
         try {
-          original = await readFile(filePath, "utf8");
+          content = await readFile(filePath);
         } catch (error) {
           if (error instanceof Error && "code" in error && error.code === "ENOENT") {
             const suggestion = await didYouMean(filePath, ctx.cwd);
@@ -383,9 +413,11 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
           );
         }
-        await requireCurrentRead(state, filePath);
+        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;
@@ -410,7 +442,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
         await writeFile(filePath, restored, "utf8");
         const snapshot = snapshotOf(restored);
-        state.reads.set(filePath, snapshot);
+        state.reads.set(key, snapshot);
         const diff = generateDiffString(original, restored);
         const text = replaceAll
           ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
@@ -421,7 +453,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original, restored),
             firstChangedLine: diff.firstChangedLine,
-            reads: { [filePath]: snapshot },
+            reads: { [key]: snapshot },
           } satisfies FileToolDetails,
         };
       });
@@ -457,11 +489,14 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       });
       return withFileMutationQueue(filePath, async () => {
         let original: string | undefined;
+        let key: string | undefined;
         try {
           const value = await stat(filePath);
           if (value.isFile()) {
-            await requireCurrentRead(state, filePath);
-            original = await readFile(filePath, "utf8");
+            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") {
@@ -472,7 +507,9 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, params.content, "utf8");
         const snapshot = snapshotOf(params.content);
-        state.reads.set(filePath, snapshot);
+        // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
+        const resolvedKey = key ?? (await readStateKey(filePath));
+        state.reads.set(resolvedKey, snapshot);
         const diff = generateDiffString(original ?? "", params.content);
         const text =
           original === undefined
@@ -484,7 +521,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original ?? "", params.content),
             firstChangedLine: diff.firstChangedLine,
-            reads: { [filePath]: snapshot },
+            reads: { [resolvedKey]: snapshot },
           } satisfies FileToolDetails,
         };
       });

package/src/claude-code/index.ts

@@ -1,6 +1,6 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { createClaudeCodeState, deserializeReads } from "./common.js";
+import { type ClaudeCodeState, createClaudeCodeState, deserializeReads } from "./common.js";
 import { registerFileTools } from "./files.js";
 import { registerSearchTools } from "./search.js";
 import { registerSessionTools } from "./session-tools.js";
@@ -9,6 +9,26 @@ import { registerShellTools } from "./shell.js";
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */
 const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write"]);
 
+/**
+ * 从当前分支的历史工具结果重建已读记账。先清空再重放，保证 state 只反映
+ * 当前分支：rewind / fork / resume 后，被抛弃分支上的 Read 不再残留。
+ */
+function restoreReads(
+  state: ClaudeCodeState,
+  sessionManager: ExtensionContext["sessionManager"],
+): void {
+  state.reads.clear();
+  for (const entry of sessionManager.getBranch()) {
+    if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+    if (!FILE_TOOL_NAMES.has(entry.message.toolName)) continue;
+    const details = entry.message.details as { reads?: unknown } | undefined;
+    if (!details?.reads) continue;
+    for (const [filePath, snapshot] of deserializeReads(details.reads)) {
+      state.reads.set(filePath, snapshot);
+    }
+  }
+}
+
 export default function claudeCodeTools(pi: ExtensionAPI): void {
   const state = createClaudeCodeState();
 
@@ -17,15 +37,14 @@ export default function claudeCodeTools(pi: ExtensionAPI): void {
   // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
   // 防呆语义不因重建而弱化。
   pi.on("session_start", (_event, ctx) => {
-    for (const entry of ctx.sessionManager.getBranch()) {
-      if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
-      if (!FILE_TOOL_NAMES.has(entry.message.toolName)) continue;
-      const details = entry.message.details as { reads?: unknown } | undefined;
-      if (!details?.reads) continue;
-      for (const [filePath, snapshot] of deserializeReads(details.reads)) {
-        state.reads.set(filePath, snapshot);
-      }
-    }
+    restoreReads(state, ctx.sessionManager);
+  });
+
+  // rewind / 树内跳转走 navigateTree → branch()，只发 session_tree 不发
+  // session_start，扩展实例也不重建。这里同样重放当前分支，丢弃被抛弃分支
+  // 的记账，避免 state 与当前分支脱节。
+  pi.on("session_tree", (_event, ctx) => {
+    restoreReads(state, ctx.sessionManager);
   });
 
   registerFileTools(pi, state);

package/src/gh-readonly.ts

@@ -34,10 +34,12 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 
-import { type ExtensionAPI, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { createSeqState } from "./lib/seq-state.js";
+
 interface GhResult {
   stdout: string;
   stderr: string;
@@ -380,8 +382,9 @@ export function stepsDetail(
   }));
 }
 
-/** In-flight dedup map to avoid concurrent fetches of the same log. */
-const inflightLogs = new Map<string, Promise<string>>();
+// 模块级串行状态：同一资源（如 CI 日志）的请求排队执行，配合函数内部的
+// 缓存检查避免重复网络请求。闭包状态不与其他扩展共享，key 无需全局前缀。
+const seq = createSeqState();
 
 async function getJobLog(
   runId: string,
@@ -393,13 +396,10 @@ async function getJobLog(
 ): Promise<string> {
   const cacheDir = join(homedir(), ".cache", "pi", "ci-logs", runId);
   const cacheFile = join(cacheDir, `${jobId}.log`);
-  const key = `${runId}:${jobId}`;
-
-  // Check in-flight dedup map
-  const inflight = inflightLogs.get(key);
-  if (inflight) return inflight;
 
-  const fetchAndCache = async (): Promise<string> => {
+  // 同一 runId:jobId 的请求串行执行：后一个进入时缓存已写入，直接命中缓存，
+  // 不会重复发网络请求；串行也保证不会有两个并发写同一 cache 文件。
+  return seq.execute(`${runId}:${jobId}`, async () => {
     // Check file cache
     try {
       return await readFile(cacheFile, "utf8");
@@ -424,20 +424,10 @@ async function getJobLog(
 
     // Write to cache
     await mkdir(cacheDir, { recursive: true });
-    await withFileMutationQueue(cacheFile, async () => {
-      await writeFile(cacheFile, log);
-    });
+    await writeFile(cacheFile, log);
 
     return log;
-  };
-
-  const promise = fetchAndCache();
-  inflightLogs.set(key, promise);
-  try {
-    return await promise;
-  } finally {
-    inflightLogs.delete(key);
-  }
+  });
 }
 
 async function resolveRepo(
@@ -1061,9 +1051,7 @@ export async function writeLogFile(
 
   const target = resolve(cwd ?? process.cwd(), outputFile);
   await mkdir(dirname(target), { recursive: true });
-  await withFileMutationQueue(target, async () => {
-    await writeFile(target, content);
-  });
+  await writeFile(target, content);
 
   const lines = content.split("\n").length;
   const bytes = Buffer.byteLength(content, "utf8");

package/src/lib/seq-state.ts

@@ -0,0 +1,34 @@
+/**
+ * 按 key 串行化并发任务：同一 key 的调用排队执行，前一个 settle（无论成败）
+ * 后才执行下一个。key 由调用方自定义（如资源 id），每个 `createSeqState()`
+ * 返回独立的闭包状态，不同扩展之间不串扰。
+ */
+
+export interface SeqState {
+  execute<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export function createSeqState(): SeqState {
+  const tails = new Map<string, Promise<unknown>>();
+
+  return {
+    execute<T>(key: string, fn: () => Promise<T>): Promise<T> {
+      const previous = tails.get(key) ?? Promise.resolve();
+
+      // 等前一个任务 settle 后执行本任务。previous 恒为 resolve（tail 吞掉了错误），
+      // 失败不会阻塞后续任务。
+      const run = previous.then(() => fn());
+
+      // 本任务的完成占位：永远 resolve，作为下一个任务的等待点。
+      // eslint-disable-next-line unicorn/no-useless-undefined -- 显式返回 undefined：吞掉前序错误并归一化为成功占位
+      const tail = run.catch(() => undefined);
+
+      tails.set(key, tail);
+      void tail.finally(() => {
+        if (tails.get(key) === tail) tails.delete(key);
+      });
+
+      return run;
+    },
+  };
+}