@trim21/personal-pi-extensions 0.1.631 → 0.1.634

package/package.json

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

package/src/claude-code/edit-match.ts

@@ -0,0 +1,44 @@
+/**
+ * Claude Code 风格的精确替换：只做精确字符串匹配（无模糊策略）。匹配在 CRLF 归一后
+ * 进行，写回时恢复原文行尾；new_string 为空且 old_string 不以换行结尾时，连同
+ * 紧随其后的换行一起删除，避免留下空行。
+ *
+ * 只处理非空 `old_string` 的替换：空 `old_string`（创建 / 填充文件）与
+ * `old_string === new_string` 的判定在调用方（带工具语义，涉及写盘与提示文案）。
+ *
+ * 抛错文案是工具契约的一部分（Claude Code 兼容），改动前先看
+ * test/claude-code-tools.test.ts 的断言。
+ */
+export function applyExactEdit(
+  original: string,
+  oldString: string,
+  newString: string,
+  replaceAll: boolean,
+): string {
+  // 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 matches = normalized.split(oldString).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}`,
+    );
+  }
+  // 删除场景（new_string 为空）：old_string 不以换行结尾且文件里是
+  // "old_string\n" 时连换行一起删，避免留下空行（对齐 Claude Code
+  // applyEditToFile 的 stripTrailingNewline 语义）
+  let searchString = oldString;
+  if (newString === "" && !oldString.endsWith("\n") && normalized.includes(oldString + "\n")) {
+    searchString = oldString + "\n";
+  }
+  // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
+  const updated = replaceAll
+    ? normalized.split(searchString).join(newString)
+    : normalized.replace(searchString, () => newString);
+  return lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
+}

package/src/claude-code/files.ts

@@ -31,6 +31,7 @@ import type { ToolPendant } from "../lib/pendant.ts";
 import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import { didYouMean, resolveToolFilePath } from "./common.js";
+import { applyExactEdit } from "./edit-match.js";
 import { convertLeadingTabsToSpaces } from "./edit-utils.js";
 
 const SAMPLE_BYTES = 4096;
@@ -170,47 +171,6 @@ export function formatReadOutput(
   return { text, totalLines };
 }
 
-function countMatches(content: string, needle: string): number {
-  if (needle === "") {
-    return 0;
-  }
-  let count = 0;
-  let index = 0;
-  while ((index = content.indexOf(needle, index)) !== -1) {
-    count++;
-    index += needle.length;
-  }
-  return count;
-}
-
-export function exactReplace(
-  content: string,
-  oldString: string,
-  newString: string,
-  replaceAll = false,
-): string {
-  if (oldString === newString) {
-    throw new Error("No changes to apply: old_string and new_string are identical.");
-  }
-  if (oldString === "") {
-    throw new Error("old_string must not be empty.");
-  }
-  const matches = countMatches(content, oldString);
-  if (matches === 0) {
-    throw new Error("String to replace not found in file.");
-  }
-  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, provide more context to make old_string unique.`,
-    );
-  }
-  if (replaceAll) {
-    return content.split(oldString).join(newString);
-  }
-  const index = content.indexOf(oldString);
-  return content.slice(0, index) + newString + content.slice(index + oldString.length);
-}
-
 export function registerFileTools(
   pi: ExtensionAPI,
   state: ReadsState,
@@ -483,37 +443,7 @@ export function registerFileTools(
         await access(filePath, constants.R_OK | constants.W_OK);
         signal?.throwIfAborted();
         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 matches = normalized.split(oldString).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}`,
-          );
-        }
-        // 删除场景（new_string 为空）：old_string 不以换行结尾且文件里是
-        // "old_string\n" 时连换行一起删，避免留下空行（对齐 Claude Code
-        // applyEditToFile 的 stripTrailingNewline 语义）
-        let searchString = oldString;
-        if (
-          newString === "" &&
-          !oldString.endsWith("\n") &&
-          normalized.includes(oldString + "\n")
-        ) {
-          searchString = oldString + "\n";
-        }
-        // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
-        const updated = replaceAll
-          ? normalized.split(searchString).join(newString)
-          : normalized.replace(searchString, () => newString);
-        const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
+        const restored = applyExactEdit(original, oldString, newString, replaceAll);
         await writeFile(filePath, restored, "utf8");
         const snapshot = snapshotOf(restored);
         state.reads.set(key, snapshot);

package/src/lib/lsp/client.ts

@@ -65,7 +65,11 @@ import {
 
 import type { LspServerHandle } from "./adapter.js";
 import { LANGUAGE_EXTENSIONS } from "./language.js";
-import { editFilePaths, stabilityAcceptable, trackStability } from "./rename.js";
+import {
+  DEFAULT_RENAME_VERIFICATION_TIMING,
+  type RenameVerificationTiming,
+  verifyRenameCoverage,
+} from "./rename.js";
 import type { FileChange, FileChangeType } from "./watcher.js";
 
 /** LSP WatchKind 位掩码（FileSystemWatcher.kind，缺省 create|change|delete）。 */
@@ -108,66 +112,11 @@ export class LspMethodNotSupportedError extends Error {
   }
 }
 
-/**
- * rename edit 未覆盖 references 看到的全部文件：服务器索引可能仍在后台加载。
- * 抛出时发生在写盘之前，整个 rename 无副作用，可稍后重试。
- */
-export class RenameIncompleteError extends Error {
-  readonly missing: readonly string[];
-  readonly extra: readonly string[];
-  constructor(missing: readonly string[], extra: readonly string[] = []) {
-    const parts: string[] = [];
-    if (missing.length > 0) {
-      parts.push(
-        `textDocument/references found the symbol in ${missing.length} file(s) ` +
-          `that the rename edit does not cover (${missing.join(", ")})`,
-      );
-    }
-    if (extra.length > 0) {
-      parts.push(
-        `the rename edit touches ${extra.length} file(s) ` +
-          `that textDocument/references did not report (${extra.join(", ")})`,
-      );
-    }
-    if (parts.length === 0) {
-      parts.push("the references result has not been stable long enough to trust");
-    }
-    super(
-      `LSP rename incomplete: ${parts.join("; ")}. ` +
-        `The server index may still be loading; nothing was modified, retry shortly.`,
-    );
-    this.missing = missing;
-    this.extra = extra;
-  }
-}
-
-/**
- * rename 覆盖校验的轮询节奏。budgetMs 是 references 收敛 + 重试的总预算；
- * 测试可临时缩小以缩短等待。
- */
-export const renameVerificationTiming = {
-  pollMs: 400,
-  budgetMs: 15_000,
-  /** ContentModified(-32801) 重试上限：服务器处理期间文档被修改，重发请求即可。 */
-  contentModifiedRetries: 3,
-  /** 接受结果所需的最少连续一致采样次数。 */
-  settleSamples: 3,
-  /** 就绪已证实（拿到过当前版本的诊断结论）时的稳定窗口下限（ms）。 */
-  stableFloorReadyMs: 400,
-  /**
-   * 就绪未证实（栅栏只是等满预算放行）时的稳定窗口下限（ms）。服务器加载
-   * 项目期间 references 只覆盖已发现的文件，残缺答案能连续多次一致（假稳定），
-   * 短窗口会把它误判成最终结果——CI 实测漏改跨文件引用，故要求 references
-   * 文件集合至少持续一致这么久才接受。
-   */
-  stableFloorUnreadyMs: 4_000,
-};
-
 /**
  * ContentModified 语义：请求处理期间 salsa 数据库被文件变更修改，服务器请
  * 客户端重发请求。重发无副作用，直接重试；仅连续超限才向上抛，避免无限循环。
  */
-async function retryOnContentModified<T>(fn: () => Promise<T>): Promise<T> {
+async function retryOnContentModified<T>(fn: () => Promise<T>, retries: number): Promise<T> {
   for (let attempt = 0; ; attempt++) {
     try {
       return await fn();
@@ -175,7 +124,7 @@ async function retryOnContentModified<T>(fn: () => Promise<T>): Promise<T> {
       if (!(error instanceof ResponseError && error.code === LSPErrorCodes.ContentModified)) {
         throw error;
       }
-      if (attempt >= renameVerificationTiming.contentModifiedRetries) {
+      if (attempt >= retries) {
         throw error;
       }
     }
@@ -348,6 +297,8 @@ export interface CreateInput {
   initializeTimeoutMs?: number;
   /** 驻留文档上限（LRU 容量，缺省 32）；超过时淘汰最久未使用并 didClose。 */
   maxOpenDocuments?: number;
+  /** 覆盖 rename 覆盖校验的轮询节奏（缺省见 DEFAULT_RENAME_VERIFICATION_TIMING）。 */
+  renameVerificationTiming?: Partial<RenameVerificationTiming>;
 }
 
 export interface LspClient {
@@ -573,6 +524,10 @@ export async function create(input: CreateInput): Promise<LspClient> {
     input.diagnosticsRequestTimeoutMs ?? clientDefaults.diagnosticsRequestTimeoutMs;
   const initializeTimeoutMs = input.initializeTimeoutMs ?? clientDefaults.initializeTimeoutMs;
   const maxOpenDocuments = input.maxOpenDocuments ?? clientDefaults.maxOpenDocuments;
+  const timing: RenameVerificationTiming = {
+    ...DEFAULT_RENAME_VERIFICATION_TIMING,
+    ...input.renameVerificationTiming,
+  };
 
   const connection = createProtocolConnection(
     new StreamMessageReader(input.server.process.stdout),
@@ -1377,7 +1332,10 @@ export async function create(input: CreateInput): Promise<LspClient> {
     signal?: AbortSignal,
   ): Promise<R> => {
     try {
-      return await retryOnContentModified(() => sendAbortableRequest(type, message, signal));
+      return await retryOnContentModified(
+        () => sendAbortableRequest(type, message, signal),
+        timing.contentModifiedRetries,
+      );
     } catch (error) {
       if (error instanceof ResponseError && error.code === ErrorCodes.MethodNotFound) {
         throw new LspMethodNotSupportedError(input.serverID, type.method);
@@ -1477,32 +1435,20 @@ export async function create(input: CreateInput): Promise<LspClient> {
       const notRenameable = () =>
         new RenameNotPossibleError(`LSP server "${input.serverID}" cannot rename at ${at}`);
 
-      // references 前置 + rename 双向校验：LSP 没有标准化的"索引完成"信号，
-      // 服务器（如 tsserver）可能在项目加载完成前回答，导致 rename 漏掉
-      // 尚未入索引的文件。对策分三层：
-      // 1. 稳定窗口：references 文件集合连续 settleSamples 次一致、且持续
-      //    一致超过稳定下限（就绪未证实用长窗口）才认为收敛，防止"服务器
-      //    根本还没发现某文件"时残缺答案的假稳定被误判为最终结果；
-      // 2. 覆盖校验（missing）：references 报告的文件必须都被 rename edit
-      //    覆盖，缺失说明服务器索引落后，抛 RenameIncompleteError；
-      // 3. 一致性校验（extra）：rename 触及的文件超出已收敛的 references
-      //    集合，说明两次请求之间项目覆盖在增长（rename 晚于 references，
-      //    索引仍在加载），此时 rename 的结果本身不可信——回到 references
-      //    轮询等重新收敛，再重发 rename 复检；预算耗尽仍不一致时抛
-      //    RenameIncompleteError——调用方尚未写盘，整个操作无副作用。
-      // 服务器不支持 references（MethodNotFound）时跳过校验，信任服务器，
-      // 与编辑器行为一致。
+      // references 前置 + rename 双向校验见 verifyRenameCoverage（三层策略的说明在那边）。
       const referencesRequest = () =>
-        retryOnContentModified(() =>
-          sendAbortableRequest(
-            ReferencesRequest.type,
-            {
-              textDocument: { uri },
-              position,
-              context: { includeDeclaration: true },
-            },
-            request.signal,
-          ),
+        retryOnContentModified(
+          () =>
+            sendAbortableRequest(
+              ReferencesRequest.type,
+              {
+                textDocument: { uri },
+                position,
+                context: { includeDeclaration: true },
+              },
+              request.signal,
+            ),
+          timing.contentModifiedRetries,
         );
 
       const toPaths = (locations: { uri: string }[] | null): Set<string> =>
@@ -1514,16 +1460,18 @@ export async function create(input: CreateInput): Promise<LspClient> {
 
       const sendRename = async (): Promise<WorkspaceEdit | null> => {
         try {
-          return await retryOnContentModified(() =>
-            sendAbortableRequest(
-              RenameRequest.type,
-              {
-                textDocument: { uri },
-                position,
-                newName: request.newName,
-              },
-              request.signal,
-            ),
+          return await retryOnContentModified(
+            () =>
+              sendAbortableRequest(
+                RenameRequest.type,
+                {
+                  textDocument: { uri },
+                  position,
+                  newName: request.newName,
+                },
+                request.signal,
+              ),
+            timing.contentModifiedRetries,
           );
         } catch (error) {
           if (error instanceof ResponseError && error.code === ErrorCodes.MethodNotFound) {
@@ -1537,12 +1485,14 @@ export async function create(input: CreateInput): Promise<LspClient> {
       if (hasPrepareProvider) {
         let prepared: PrepareRenameResult | null;
         try {
-          prepared = await retryOnContentModified(() =>
-            sendAbortableRequest(
-              PrepareRenameRequest.type,
-              { textDocument: { uri }, position },
-              request.signal,
-            ),
+          prepared = await retryOnContentModified(
+            () =>
+              sendAbortableRequest(
+                PrepareRenameRequest.type,
+                { textDocument: { uri }, position },
+                request.signal,
+              ),
+            timing.contentModifiedRetries,
           );
         } catch (error) {
           if (error instanceof ResponseError && error.code === ErrorCodes.MethodNotFound) {
@@ -1572,63 +1522,18 @@ export async function create(input: CreateInput): Promise<LspClient> {
         return placeholder === undefined ? { edit } : { edit, placeholder };
       }
 
-      const minStableMs = indexReady
-        ? renameVerificationTiming.stableFloorReadyMs
-        : renameVerificationTiming.stableFloorUnreadyMs;
-      const deadline = Date.now() + renameVerificationTiming.budgetMs;
-      let stability = trackStability({
-        previous: undefined,
-        paths: toPaths(locations),
-        now: Date.now(),
+      const edit = await verifyRenameCoverage({
+        indexReady,
+        timing,
+        initialPaths: toPaths(locations),
+        refetchPaths: async () => toPaths(await referencesRequest()),
+        sendRename: async () => (await sendRename()) ?? null,
+        sleep: sleepWithSignal,
+        now: () => Date.now(),
+        notRenameable,
+        signal: request.signal,
       });
-      for (;;) {
-        request.signal?.throwIfAborted();
-        const now = Date.now();
-        const stable = stabilityAcceptable(stability, {
-          now,
-          minSamples: renameVerificationTiming.settleSamples,
-          minStableMs,
-        });
-        const expired = now >= deadline;
-        if (stable || expired) {
-          const edit = await sendRename();
-          if (!edit) {
-            throw notRenameable();
-          }
-          const editPaths = editFilePaths(edit);
-          const missing: string[] = [];
-          const extra: string[] = [];
-          for (const path of stability.paths) {
-            if (!editPaths.has(path)) {
-              missing.push(path);
-            }
-          }
-          for (const path of editPaths) {
-            if (!stability.paths.has(path)) {
-              extra.push(path);
-            }
-          }
-          if (missing.length === 0 && extra.length === 0) {
-            if (stable) {
-              return placeholder === undefined ? { edit } : { edit, placeholder };
-            }
-            // 双向一致但稳定窗口未达标：索引可能仍在加载、残缺答案假稳定，
-            // 宁可报可重试的不完整错误，也不把残缺结果当成功写盘。
-            throw new RenameIncompleteError([], []);
-          }
-          if (expired || missing.length > 0) {
-            throw new RenameIncompleteError(missing, extra);
-          }
-          // rename 报出 references 没有的文件：references 快照已过时，
-          // 继续轮询到重新收敛后再重发 rename 复检（预算耗尽则向上抛）。
-        }
-        await sleepWithSignal(renameVerificationTiming.pollMs, request.signal);
-        stability = trackStability({
-          previous: stability,
-          paths: toPaths(await referencesRequest()),
-          now: Date.now(),
-        });
-      }
+      return placeholder === undefined ? { edit } : { edit, placeholder };
     },
     async definition(request: InspectPositionRequest): Promise<InspectLocation[]> {
       const { uri, position } = await preparePositionRequest(request);

package/src/lib/lsp/rename.ts

@@ -6,7 +6,9 @@
  * - lineCandidates：character 缺省时在一行内按词边界枚举候选位置，
  *   供逐候选探测消歧；
  * - canonicalizeEdit：把两次 rename 的结果归一化成稳定字符串，
- *   比较它们是否指向同一个符号（同名歧义消解）。
+ *   比较它们是否指向同一个符号（同名歧义消解）；
+ * - verifyRenameCoverage：等 references 的稳定窗口收敛，再双向校验 rename edit
+ *   的覆盖（missing / extra），不满足时抛 RenameIncompleteError。
  *
  * 位置语义按 LSP 规范：0-based 行列，character 为 UTF-16 code unit，
  * 行内容不含行结束符（CRLF 的 \r 不计入列号）。
@@ -243,6 +245,177 @@ export function stabilityAcceptable(
   return run.samples >= input.minSamples && input.now - run.since >= input.minStableMs;
 }
 
+/**
+ * rename edit 未覆盖 references 看到的全部文件：服务器索引可能仍在后台加载。
+ * 抛出时发生在写盘之前，整个 rename 无副作用，可稍后重试。
+ */
+export class RenameIncompleteError extends Error {
+  readonly missing: readonly string[];
+  readonly extra: readonly string[];
+  constructor(missing: readonly string[], extra: readonly string[] = []) {
+    const parts: string[] = [];
+    if (missing.length > 0) {
+      parts.push(
+        `textDocument/references found the symbol in ${missing.length} file(s) ` +
+          `that the rename edit does not cover (${missing.join(", ")})`,
+      );
+    }
+    if (extra.length > 0) {
+      parts.push(
+        `the rename edit touches ${extra.length} file(s) ` +
+          `that textDocument/references did not report (${extra.join(", ")})`,
+      );
+    }
+    if (parts.length === 0) {
+      parts.push("the references result has not been stable long enough to trust");
+    }
+    super(
+      `LSP rename incomplete: ${parts.join("; ")}. ` +
+        `The server index may still be loading; nothing was modified, retry shortly.`,
+    );
+    this.missing = missing;
+    this.extra = extra;
+  }
+}
+
+/**
+ * rename 覆盖校验的轮询节奏。budgetMs 是 references 收敛 + 重试的总预算；
+ * 缺省见 DEFAULT_RENAME_VERIFICATION_TIMING，client 与测试按需覆盖。
+ */
+export interface RenameVerificationTiming {
+  pollMs: number;
+  budgetMs: number;
+  /** ContentModified(-32801) 重试上限：服务器处理期间文档被修改，重发请求即可。 */
+  contentModifiedRetries: number;
+  /** 接受结果所需的最少连续一致采样次数。 */
+  settleSamples: number;
+  /** 就绪已证实（拿到过当前版本的诊断结论）时的稳定窗口下限（ms）。 */
+  stableFloorReadyMs: number;
+  /**
+   * 就绪未证实（栅栏只是等满预算放行）时的稳定窗口下限（ms）。服务器加载
+   * 项目期间 references 只覆盖已发现的文件，残缺答案能连续多次一致（假稳定），
+   * 短窗口会把它误判成最终结果——CI 实测漏改跨文件引用，故要求 references
+   * 文件集合至少持续一致这么久才接受。
+   */
+  stableFloorUnreadyMs: number;
+}
+
+/** rename 覆盖校验的缺省节奏（每个 client 可用创建参数局部覆盖）。 */
+export const DEFAULT_RENAME_VERIFICATION_TIMING: RenameVerificationTiming = {
+  pollMs: 400,
+  budgetMs: 15_000,
+  contentModifiedRetries: 3,
+  settleSamples: 3,
+  stableFloorReadyMs: 400,
+  stableFloorUnreadyMs: 4_000,
+};
+
+/** verifyRenameCoverage 的输入：依赖全部注入，收敛序列与预算可直接构造。 */
+export interface RenameCoverageOptions {
+  /** 就绪栅栏：是否已证实拿到当前版本的诊断结论（决定稳定窗口下限）。 */
+  indexReady: boolean;
+  timing: RenameVerificationTiming;
+  /** 进入校验前已采到的那一份 references 文件集合。 */
+  initialPaths: ReadonlySet<string>;
+  /** 后续采样：再请求一次 references 并给出文件集合。 */
+  refetchPaths: () => Promise<ReadonlySet<string>>;
+  /** 发一次 rename；返回 null 表示服务器拒绝重命名。 */
+  sendRename: () => Promise<WorkspaceEdit | null>;
+  /** 等待一次轮询间隔。 */
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+  /** 当前时间戳（ms）。 */
+  now: () => number;
+  /** 构造「该位置不可重命名」错误：消息含 serverID 与位置，由调用方提供。 */
+  notRenameable: () => Error;
+  signal?: AbortSignal;
+}
+
+/**
+ * 等 references 收敛并双向校验 rename 覆盖，返回 edit；不满足覆盖要求时抛
+ * RenameIncompleteError。
+ *
+ * references 前置 + rename 双向校验：LSP 没有标准化的"索引完成"信号，
+ * 服务器（如 tsserver）可能在项目加载完成前回答，导致 rename 漏掉
+ * 尚未入索引的文件。对策分三层：
+ * 1. 稳定窗口：references 文件集合连续 settleSamples 次一致、且持续
+ *    一致超过稳定下限（就绪未证实用长窗口）才认为收敛，防止"服务器
+ *    根本还没发现某文件"时残缺答案的假稳定被误判为最终结果；
+ * 2. 覆盖校验（missing）：references 报告的文件必须都被 rename edit
+ *    覆盖，缺失说明服务器索引落后，抛 RenameIncompleteError；
+ * 3. 一致性校验（extra）：rename 触及的文件超出已收敛的 references
+ *    集合，说明两次请求之间项目覆盖在增长（rename 晚于 references，
+ *    索引仍在加载），此时 rename 的结果本身不可信——回到 references
+ *    轮询等重新收敛，再重发 rename 复检；预算耗尽仍不一致时抛
+ *    RenameIncompleteError——调用方尚未写盘，整个操作无副作用。
+ *
+ * 首次采样由调用方发起（initialPaths），本函数只负责后续的 refetchPaths
+ * 采样，所以请求次数与调用方内联轮询时逐次一致；服务器不支持
+ * references（MethodNotFound）时由调用方跳过本校验，信任服务器。
+ *
+ * 判定顺序是行为的一部分：双向一致但稳定窗口未达标时抛的是
+ * RenameIncompleteError([], [])（残缺答案假稳定），而非带上 missing 的错误。
+ */
+export async function verifyRenameCoverage(options: RenameCoverageOptions): Promise<WorkspaceEdit> {
+  const {
+    indexReady,
+    timing,
+    initialPaths,
+    refetchPaths,
+    sendRename,
+    sleep,
+    now,
+    notRenameable,
+    signal,
+  } = options;
+  const minStableMs = indexReady ? timing.stableFloorReadyMs : timing.stableFloorUnreadyMs;
+  const deadline = now() + timing.budgetMs;
+  let stability = trackStability({ previous: undefined, paths: initialPaths, now: now() });
+  for (;;) {
+    signal?.throwIfAborted();
+    const at = now();
+    const stable = stabilityAcceptable(stability, {
+      now: at,
+      minSamples: timing.settleSamples,
+      minStableMs,
+    });
+    const expired = at >= deadline;
+    if (stable || expired) {
+      const edit = await sendRename();
+      if (!edit) {
+        throw notRenameable();
+      }
+      const editPaths = editFilePaths(edit);
+      const missing: string[] = [];
+      const extra: string[] = [];
+      for (const path of stability.paths) {
+        if (!editPaths.has(path)) {
+          missing.push(path);
+        }
+      }
+      for (const path of editPaths) {
+        if (!stability.paths.has(path)) {
+          extra.push(path);
+        }
+      }
+      if (missing.length === 0 && extra.length === 0) {
+        if (stable) {
+          return edit;
+        }
+        // 双向一致但稳定窗口未达标：索引可能仍在加载、残缺答案假稳定，
+        // 宁可报可重试的不完整错误，也不把残缺结果当成功写盘。
+        throw new RenameIncompleteError([], []);
+      }
+      if (expired || missing.length > 0) {
+        throw new RenameIncompleteError(missing, extra);
+      }
+      // rename 报出 references 没有的文件：references 快照已过时，
+      // 继续轮询到重新收敛后再重发 rename 复检（预算耗尽则向上抛）。
+    }
+    await sleep(timing.pollMs, signal);
+    stability = trackStability({ previous: stability, paths: await refetchPaths(), now: now() });
+  }
+}
+
 /**
  * 一行内 `symbol` 的候选位置（0-based，列相对行首）：
  * - `character` 缺省：枚举行内与 `symbol` 相同的词出现位置；

package/src/spawn-agent-progress.ts

@@ -0,0 +1,214 @@
+/**
+ * Progress state machine for the `spawn_agent` tool.
+ *
+ * The parent sees a rolling log: `tool: <name>` lines for tool calls and
+ * `text: <content>` lines for completed text blocks, keeping the last
+ * `MAX_PROGRESS_LINES` lines. Consecutive tool calls are merged into a single
+ * `tool:` line (`read x 2, glob`) and the merged content is folded to the
+ * first/last 9 chars joined by `…`, so a burst of tool calls or a long text
+ * block does not flood the window. Only a text block starts a new line —
+ * thinking is a transient status line, so it does not break the merge across
+ * turn boundaries. Line content is sanitized first: markdown marker characters
+ * are stripped and whitespace (including newlines) is collapsed to single
+ * spaces, so one log entry is always exactly one rendered line.
+ *
+ * The rendered panel is the window, then an optional transient
+ * `thinking ( N chars )` line while the model is thinking, then a fixed footer
+ * line: the subagent name as a code span (`` `scout` ``) followed by the live
+ * usage stats when there are any. The thinking line and the footer ride
+ * outside the rolling window, so the footer is never trimmed. The model name
+ * on the footer is the model the session actually uses, which differs from the
+ * frontmatter string when the declared model resolved to nothing and the SDK
+ * fell back to a default.
+ *
+ * State is held in the closure of a `createSubagentProgress` instance, one per
+ * run. The `noteX` methods only mutate state and return nothing; pushing the
+ * rendered text to the host (`onUpdate`) is the caller's job, so the caller
+ * decides when a state change is worth a refresh.
+ */
+
+/**
+ * Progress log keeps only the most recent lines (rolling window).
+ * 展开后面板最多 6 行内容：4 行日志 + 可能的一行瞬态 thinking + 固定的 metadata 行。
+ */
+const MAX_PROGRESS_LINES = 4;
+/** Progress line content (without the `tool:` / `text:` prefix) is capped at 21 chars; longer text is folded to the first/last 9 chars joined by ` … `. */
+const MAX_PROGRESS_CHARS_PER_LINE = 21;
+/**
+ * 进度内容会被 pi 按 markdown 渲染，这些标记字符会改变显示效果（代码块、粗体、
+ * 链接、标题等），因此在进日志前统一删掉。
+ */
+const PROGRESS_MARKDOWN_MARKERS_RE = /[`*_~[\]<>#|]/g;
+
+/** 进度面板要展示的运行统计（`runAgent` 的 `result.usage`）。 */
+export interface ProgressUsage {
+  turns: number;
+  cost: number;
+  contextTokens: number;
+}
+
+/** 一次子代理运行的进度状态机：改状态用 `noteX`，取文本用 `render`。 */
+export interface SubagentProgress {
+  /** 工具调用开始：合并进当前 `tool:` 行。 */
+  noteToolCall(rawName: string): void;
+  /** 一个完成的 text 块：作为 `text:` 行写入并打断工具合并。 */
+  noteTextBlock(content: string): void;
+  /** thinking 开始：打开瞬态行（计数从 0 开始）。 */
+  thinkingStart(): void;
+  /** thinking 增量：累加字符数。 */
+  thinkingDelta(length: number): void;
+  /** thinking 结束：关闭瞬态行。 */
+  thinkingEnd(): void;
+  /** 渲染面板：滚动窗口 + 瞬态 thinking 行 + footer。 */
+  render(usage: ProgressUsage, model?: string): string;
+}
+
+/**
+ * Fold over-long progress line content: keep the first/last 9 chars joined by
+ * ` … ` (space, ellipsis, space), so the folded line never exceeds
+ * `MAX_PROGRESS_CHARS_PER_LINE` chars (9 + 3 + 9 = 21). Shorter text is
+ * returned as-is.
+ */
+function foldProgressLine(text: string): string {
+  if (text.length <= MAX_PROGRESS_CHARS_PER_LINE) {
+    return text;
+  }
+  const keep = Math.floor((MAX_PROGRESS_CHARS_PER_LINE - 3) / 2);
+  return `${text.slice(0, keep)} … ${text.slice(-keep)}`;
+}
+
+/**
+ * 进度行是「单行内容 + markdown 渲染」：内容里的换行会打乱按行滚动的窗口，
+ * markdown 标记会改变渲染效果。先删掉标记字符，再把换行/制表符/连续空格折成
+ * 单个空格并去掉首尾空白，保证一条日志恒为一行。
+ */
+function sanitizeProgressLine(text: string): string {
+  return text.replaceAll(PROGRESS_MARKDOWN_MARKERS_RE, "").replaceAll(/\s+/g, " ").trim();
+}
+
+/**
+ * token 计数的可读格式。进度面板 footer 与 spawn_agent 的输出截断提示共用，
+ * 改动会同时影响两处。
+ */
+export function formatTokens(count: number): string {
+  if (count < 1000) {
+    return count.toString();
+  }
+  if (count < 10_000) {
+    return `${(count / 1000).toFixed(1)}k`;
+  }
+  if (count < 1_000_000) {
+    return `${Math.round(count / 1000)}k`;
+  }
+  return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+function formatUsageStats(usage: ProgressUsage, model?: string): string {
+  const parts: string[] = [];
+  if (usage.turns) {
+    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+  }
+  if (usage.cost) {
+    parts.push(`$${usage.cost.toFixed(4)}`);
+  }
+  if (usage.contextTokens > 0) {
+    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+  }
+  if (model) {
+    parts.push(model);
+  }
+  return parts.join(" ");
+}
+
+function toolSegment(name: string, count: number): string {
+  return count > 1 ? `${name} x ${count}` : name;
+}
+
+/**
+ * Create the progress state machine for one subagent run.
+ *
+ * `maxLines` only controls the rolling window of log lines — the transient
+ * thinking line and the footer ride outside it. Defaults to
+ * `MAX_PROGRESS_LINES`.
+ */
+export function createSubagentProgress(options: {
+  /** 面板标题（子代理名）。 */
+  name: string;
+  /** 滚动窗口行数，缺省 4。 */
+  maxLines?: number;
+}): SubagentProgress {
+  const maxLines = options.maxLines ?? MAX_PROGRESS_LINES;
+  let logLines: string[] = [];
+  // 工具调用行合并:连续的 tool_execution_start 事件合并在同一 `tool:` 行
+  // (如 `tool: read x 2, glob`),相同工具名连续出现时计为 `name x N`,
+  // 不同名按调用顺序罗列;只有写入日志行的事件(text 块)打断合并,thinking
+  // 不写日志行、也不打断合并。
+  let toolLineSegments: string[] = [];
+  let toolLine: { name: string; count: number } | undefined;
+  // 思考中状态：thinkingStart 打开、thinkingDelta 累计字符数、thinkingEnd
+  // 关闭；非 undefined 时 render 在 footer 上方插一行瞬态 thinking 状态。
+  let thinkingChars: number | undefined;
+
+  function pushLogLine(line: string) {
+    logLines.push(line);
+    if (logLines.length > maxLines) {
+      logLines = logLines.slice(-maxLines);
+    }
+    // 写进日志的新行都会打断工具调用合并,下一批调用另起一行。
+    toolLine = undefined;
+  }
+
+  function appendToolLine(rawName: string) {
+    const name = sanitizeProgressLine(rawName);
+    const firstInBatch = toolLine === undefined;
+    if (toolLine === undefined) {
+      toolLineSegments = [];
+      toolLine = { name, count: 1 };
+    } else if (toolLine.name === name) {
+      toolLine.count++;
+    } else {
+      toolLineSegments.push(toolSegment(toolLine.name, toolLine.count));
+      toolLine = { name, count: 1 };
+    }
+    const parts = [...toolLineSegments, toolSegment(toolLine.name, toolLine.count)].join(", ");
+    const line = `tool: ${foldProgressLine(parts)}`;
+    if (firstInBatch) {
+      logLines.push(line);
+      if (logLines.length > maxLines) {
+        logLines = logLines.slice(-maxLines);
+      }
+    } else {
+      logLines[logLines.length - 1] = line;
+    }
+  }
+
+  return {
+    noteToolCall: appendToolLine,
+    noteTextBlock(content) {
+      pushLogLine(`text: ${foldProgressLine(sanitizeProgressLine(content))}`);
+    },
+    thinkingStart() {
+      thinkingChars = 0;
+    },
+    thinkingDelta(length) {
+      thinkingChars = (thinkingChars ?? 0) + length;
+    },
+    thinkingEnd() {
+      thinkingChars = undefined;
+    },
+    render(usage, model) {
+      // 最后一行固定是「子代理名 + 运行中统计」：名字用 code span 标出，进度流里
+      // 一眼能看出属于哪个 subagent；usage 与它同行，TUI 始终能看到实时 token 开销。
+      // 这行位于滚动窗口之外，因此永远不会被挤掉。
+      const usageLine = formatUsageStats(usage, model);
+      const name = sanitizeProgressLine(options.name);
+      const footer = usageLine ? `\`${name}\` ${usageLine}` : `\`${name}\``;
+      const lines = [...logLines];
+      if (thinkingChars !== undefined) {
+        lines.push(`thinking ( ${thinkingChars} chars )`);
+      }
+      lines.push(footer);
+      return lines.join("\n");
+    },
+  };
+}

package/src/spawn-agent.ts

@@ -12,8 +12,8 @@
  * returns its final output to the parent model. Progress is streamed through
  * `onUpdate`, the same channel the built-in bash tool uses for live output.
  * Progress is a rolling log: `tool: <name>` lines for tool calls and
- * `text: <content>` lines for completed text blocks, keeping the last
- * `MAX_PROGRESS_LINES` lines. Consecutive tool calls are merged into a
+ * `text: <content>` lines for completed text blocks, keeping only the last few
+ * lines (`MAX_PROGRESS_LINES` in spawn-agent-progress.ts). Consecutive tool calls are merged into a
  * single `tool:` line (`read x 2, glob`) and over-long line content is
  * folded to the first/last 9 chars joined by `…`, so a burst of tool calls
  * or a long text block does not flood the window; only a text block starts
@@ -79,6 +79,7 @@ import {
   formatAgentList,
   loadSpawnAgentConfig,
 } from "./spawn-agent-agents.js";
+import { createSubagentProgress, formatTokens } from "./spawn-agent-progress.js";
 
 // ── constants ────────────────────────────────────────────────────────────────
 
@@ -96,18 +97,6 @@ export const SUBAGENT_DEFAULT_SANDBOX: BwrapConfig = completeBwrapConfig({
   fs: { mode: "readonly" },
   network: { mode: "block" },
 });
-/**
- * Progress log keeps only the most recent lines (rolling window).
- * 展开后面板最多 6 行内容：4 行日志 + 可能的一行瞬态 thinking + 固定的 metadata 行。
- */
-const MAX_PROGRESS_LINES = 4;
-/** Progress line content (without the `tool:` / `text:` prefix) is capped at 21 chars; longer text is folded to the first/last 9 chars joined by ` … `. */
-const MAX_PROGRESS_CHARS_PER_LINE = 21;
-/**
- * 进度内容会被 pi 按 markdown 渲染，这些标记字符会改变显示效果（代码块、粗体、
- * 链接、标题等），因此在进日志前统一删掉。
- */
-const PROGRESS_MARKDOWN_MARKERS_RE = /[`*_~[\]<>#|]/g;
 /** 错误消息里 stderr 的展示上限。 */
 const MAX_STDERR_ERROR_BYTES = 4 * 1024;
 /** 全局默认配置：~/.pi/agent/spawn-agent.json，字段可被 frontmatter 覆盖。 */
@@ -231,59 +220,6 @@ export function formatSubagentError(result: SubagentResult): { reason: string; m
   return { reason, message: parts.length > 0 ? parts.join("\n") : "(no output)" };
 }
 
-/**
- * Fold over-long progress line content: keep the first/last 9 chars joined by
- * ` … ` (space, ellipsis, space), so the folded line never exceeds
- * `MAX_PROGRESS_CHARS_PER_LINE` chars (9 + 3 + 9 = 21). Shorter text is
- * returned as-is.
- */
-function foldProgressLine(text: string): string {
-  if (text.length <= MAX_PROGRESS_CHARS_PER_LINE) {
-    return text;
-  }
-  const keep = Math.floor((MAX_PROGRESS_CHARS_PER_LINE - 3) / 2);
-  return `${text.slice(0, keep)} … ${text.slice(-keep)}`;
-}
-
-/**
- * 进度行是「单行内容 + markdown 渲染」：内容里的换行会打乱按行滚动的窗口，
- * markdown 标记会改变渲染效果。先删掉标记字符，再把换行/制表符/连续空格折成
- * 单个空格并去掉首尾空白，保证一条日志恒为一行。
- */
-function sanitizeProgressLine(text: string): string {
-  return text.replaceAll(PROGRESS_MARKDOWN_MARKERS_RE, "").replaceAll(/\s+/g, " ").trim();
-}
-
-function formatTokens(count: number): string {
-  if (count < 1000) {
-    return count.toString();
-  }
-  if (count < 10_000) {
-    return `${(count / 1000).toFixed(1)}k`;
-  }
-  if (count < 1_000_000) {
-    return `${Math.round(count / 1000)}k`;
-  }
-  return `${(count / 1_000_000).toFixed(1)}M`;
-}
-
-function formatUsageStats(usage: UsageStats, model?: string): string {
-  const parts: string[] = [];
-  if (usage.turns) {
-    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-  }
-  if (usage.cost) {
-    parts.push(`$${usage.cost.toFixed(4)}`);
-  }
-  if (usage.contextTokens > 0) {
-    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-  }
-  if (model) {
-    parts.push(model);
-  }
-  return parts.join(" ");
-}
-
 /** 子 agent 结果的折叠面板 markdown：父 agent 的 prompt 与父 agent 看到的结果。 */
 function formatPendantMarkdown(task: string, response: string): string {
   return `# prompt:\n${task.trim()}\n# response\n${response.trim()}`;
@@ -375,10 +311,6 @@ export function resolveModel(
 
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
-function toolSegment(name: string, count: number): string {
-  return count > 1 ? `${name} x ${count}` : name;
-}
-
 /** The subset of AgentSession runAgent relies on (injectable for tests). */
 export interface SubagentSession {
   agent: { state: { messages: AgentMessage[] } };
@@ -478,65 +410,11 @@ export async function runAgent(
   // fallback 到默认模型，回显配置原文会掩盖这次 fallback。
   result.model = session.model?.id;
 
-  let logLines: string[] = [];
-  // 工具调用行合并:连续的 tool_execution_start 事件合并在同一 `tool:` 行
-  // (如 `tool: read x 2, glob`),相同工具名连续出现时计为 `name x N`,
-  // 不同名按调用顺序罗列;只有写入日志行的事件(text 块)打断合并,thinking
-  // 不写日志行、也不打断合并。
-  let toolLineSegments: string[] = [];
-  let toolLine: { name: string; count: number } | undefined;
-  // 思考中状态：thinking_start 打开、thinking_delta 累计字符数、thinking_end
-  // 关闭；非 undefined 时 emitUpdate 在 footer 上方插一行瞬态 thinking 状态。
-  let thinkingChars: number | undefined;
-
-  const pushLogLine = (line: string) => {
-    logLines.push(line);
-    if (logLines.length > MAX_PROGRESS_LINES) {
-      logLines = logLines.slice(-MAX_PROGRESS_LINES);
-    }
-    // 写进日志的新行都会打断工具调用合并,下一批调用另起一行。
-    toolLine = undefined;
-  };
-
-  const appendToolLine = (rawName: string) => {
-    const name = sanitizeProgressLine(rawName);
-    const firstInBatch = toolLine === undefined;
-    if (toolLine === undefined) {
-      toolLineSegments = [];
-      toolLine = { name, count: 1 };
-    } else if (toolLine.name === name) {
-      toolLine.count++;
-    } else {
-      toolLineSegments.push(toolSegment(toolLine.name, toolLine.count));
-      toolLine = { name, count: 1 };
-    }
-    const parts = [...toolLineSegments, toolSegment(toolLine.name, toolLine.count)].join(", ");
-    const line = `tool: ${foldProgressLine(parts)}`;
-    if (firstInBatch) {
-      logLines.push(line);
-      if (logLines.length > MAX_PROGRESS_LINES) {
-        logLines = logLines.slice(-MAX_PROGRESS_LINES);
-      }
-    } else {
-      logLines[logLines.length - 1] = line;
-    }
-    emitUpdate();
-  };
+  const progress = createSubagentProgress({ name: result.agent });
 
   const emitUpdate = () => {
-    // 最后一行固定是「子代理名 + 运行中统计」：名字用 code span 标出，进度流里
-    // 一眼能看出属于哪个 subagent；usage 与它同行，TUI 始终能看到实时 token 开销。
-    // 这行位于滚动窗口之外，因此永远不会被挤掉。
-    const usageLine = formatUsageStats(result.usage, result.model);
-    const name = sanitizeProgressLine(result.agent);
-    const footer = usageLine ? `\`${name}\` ${usageLine}` : `\`${name}\``;
-    const lines = [...logLines];
-    if (thinkingChars !== undefined) {
-      lines.push(`thinking ( ${thinkingChars} chars )`);
-    }
-    lines.push(footer);
     onUpdate?.({
-      content: [{ type: "text", text: lines.join("\n") }],
+      content: [{ type: "text", text: progress.render(result.usage, result.model) }],
       details: {},
     });
   };
@@ -550,24 +428,24 @@ export async function runAgent(
         const delta = event.assistantMessageEvent;
         switch (delta.type) {
           case "text_end": {
-            pushLogLine(`text: ${foldProgressLine(sanitizeProgressLine(delta.content))}`);
+            progress.noteTextBlock(delta.content);
             emitUpdate();
             break;
           }
           case "thinking_start": {
             // thinking 不产生日志行，因此不打断工具行合并：跨轮次的连续工具调用
             // 仍累加到同一 `tool:` 行。
-            thinkingChars = 0;
+            progress.thinkingStart();
             emitUpdate();
             break;
           }
           case "thinking_delta": {
-            thinkingChars = (thinkingChars ?? 0) + delta.delta.length;
+            progress.thinkingDelta(delta.delta.length);
             emitUpdate();
             break;
           }
           case "thinking_end": {
-            thinkingChars = undefined;
+            progress.thinkingEnd();
             emitUpdate();
             break;
           }
@@ -577,7 +455,8 @@ export async function runAgent(
         break;
       }
       case "tool_execution_start": {
-        appendToolLine(event.toolName);
+        progress.noteToolCall(event.toolName);
+        emitUpdate();
         break;
       }
       case "message_end": {