@trim21/personal-pi-extensions 0.1.564 → 0.1.570

package/package.json

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

package/src/claude-code/files.ts

@@ -120,9 +120,10 @@ function splitFileLines(content: string): string[] {
  * 易误判多一层缩进。limit 未指定时读取全部。无 PARTIAL 提示、无单行截断
  * （由 execute 层的字节/token 上限兜底）。
  *
- * offset 为负数时从文件末尾倒数（`offset=-5` 等价 `tail -n 5`），超出文件
- * 长度时钳到文件开头（与 tail 一致，不告警）。输出行号始终为绝对行号；
- * offset=0 的「行号从 0 起」是对齐 Claude Code lineOffset 的历史语义。
+ * offset 为负数时从文件末尾倒数（`offset=-5` 等价 `tail -n 5`）——倒数按**真实
+ * 行**计算，splitFileLines 补出的尾随幻影行不算一行也不在输出里；超出文件长度时
+ * 钳到文件开头（与 tail 一致，不告警）。输出行号始终为绝对行号；offset=0 的
+ * 「行号从 0 起」是对齐 Claude Code lineOffset 的历史语义。
  */
 export function formatReadOutput(
   content: string,
@@ -143,10 +144,18 @@ export function formatReadOutput(
       totalLines,
     };
   }
-  const startIndex = offset === 0 ? 0 : offset > 0 ? offset - 1 : Math.max(totalLines + offset, 0);
+  // 尾随幻影行（splitFileLines 补的那个 \n）不对应文件内容：负 offset 按真实行
+  // 从末尾倒数，窗口也不含它，否则 `offset=-1` 只会读到一个空行。
+  const realLines = totalLines - 1;
+  const fromTail = offset < 0;
+  const startIndex = fromTail ? Math.max(realLines + offset, 0) : offset === 0 ? 0 : offset - 1;
   const firstLine = offset === 0 ? 0 : startIndex + 1;
-  const selected =
-    limit === undefined ? lines.slice(startIndex) : lines.slice(startIndex, startIndex + limit);
+  const endIndex = fromTail
+    ? Math.min(limit === undefined ? realLines : startIndex + limit, realLines)
+    : limit === undefined
+      ? totalLines
+      : startIndex + limit;
+  const selected = lines.slice(startIndex, endIndex);
   const text = selected.map((line, index) => `${firstLine + index}: ${line}`).join("\n");
   return { text, totalLines };
 }
@@ -342,6 +351,7 @@ export function registerFileTools(
       // 与 Edit / Write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
       const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
         notify: (message, level) => ctx.ui.notify(message, level),
+        signal,
       });
       return {
         content: [
@@ -402,6 +412,7 @@ export function registerFileTools(
           replaceAll: params.replace_all,
         },
         policy,
+        signal,
       });
       const [message, details, diagnostics] = await withFileMutationQueue<
         [string, FileToolDetails, DiagnosticReport]
@@ -535,6 +546,7 @@ export function registerFileTools(
         signal?.throwIfAborted();
         const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
           notify: (message, level) => ctx.ui.notify(message, level),
+          signal,
         });
         return [
           text,
@@ -598,6 +610,7 @@ export function registerFileTools(
         absolutePath: filePath,
         change: { oldText: "", newText: params.content },
         policy,
+        signal,
       });
       const [message, details, diagnostics] = await withFileMutationQueue<
         [string, FileToolDetails, DiagnosticReport]
@@ -632,6 +645,7 @@ export function registerFileTools(
         signal?.throwIfAborted();
         const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
           notify: (message, level) => ctx.ui.notify(message, level),
+          signal,
         });
         return [
           text,

package/src/lib/lsp/client.ts

@@ -14,6 +14,7 @@ import { extname, isAbsolute, normalize, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import {
+  CancellationTokenSource,
   createMessageConnection,
   type MessageConnection,
   ResponseError,
@@ -161,6 +162,8 @@ export interface RenameSymbolRequest {
   line: number;
   character: number;
   newName: string;
+  /** 调用方取消信号：中止时立刻放弃等待并通知服务器取消。 */
+  signal?: AbortSignal;
 }
 
 export interface RenameSymbolResult {
@@ -174,6 +177,8 @@ export interface InspectPositionRequest {
   path: string;
   line: number;
   character: number;
+  /** 调用方取消信号：中止时立刻放弃等待并通知服务器取消。 */
+  signal?: AbortSignal;
 }
 
 /** definition / references 归一化后的位置（0-based；1-based 格式化由工具层负责）。 */
@@ -433,6 +438,31 @@ async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
 
 const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
+/** 中止请求时的拒绝原因：沿用 signal.reason（默认是 name=AbortError 的 DOMException）。 */
+function abortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error("The operation was aborted");
+}
+
+/** 可中止的 sleep：中止时以 signal.reason 拒绝，而不是白等到轮询间隔结束。 */
+function sleepWithSignal(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  if (!signal) return sleep(ms);
+  return new Promise<void>((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 /** pull 诊断失败后的重试间隔。 */
 const PULL_RETRY_INTERVAL_MS = 100;
 
@@ -457,6 +487,37 @@ function stopProcess(process: LspServerHandle["process"]): Promise<void> {
   });
 }
 
+/**
+ * 驻留文档超容量时的淘汰计划（纯函数，见 create 里的 evictExcess）：
+ * - `stale`：lruOrder 里已不在 files 的陈旧 key（被 watchedFiles 的 didClose 移出），
+ *   不占容量，直接回收；
+ * - `evict`：按使用顺序（最久未用在前）应 didClose 的路径。
+ *
+ * 容量是**尽力而为**的上限：正在等诊断的文档必须留到诊断收集完（关闭会抹掉
+ * 本次写入的诊断结果），因此可淘汰项不足时宁可少淘汰几个（甚至一个都不淘汰），
+ * 把收敛留给后续 openDocument。调用方的淘汰循环必须单次有界——等待窗口内的文档
+ * 若被当成"稍后重试"的对象，就是同步自旋（那部分代码里没有 await），会把事件
+ * 循环整个锁死。
+ */
+export function evictionPlan(options: {
+  /** lruOrder 的迭代序：最久未用在前。 */
+  order: readonly string[];
+  /** 该路径是否仍在驻留集合（files）里。 */
+  isResident: (path: string) => boolean;
+  /** 该路径是否正在等诊断。 */
+  isWaiting: (path: string) => boolean;
+  maxOpenDocuments: number;
+}): { stale: string[]; evict: string[] } {
+  const stale: string[] = [];
+  const evictable: string[] = [];
+  for (const path of options.order) {
+    if (!options.isResident(path)) stale.push(path);
+    else if (!options.isWaiting(path)) evictable.push(path);
+  }
+  const excess = options.order.length - stale.length - options.maxOpenDocuments;
+  return { stale, evict: excess > 0 ? evictable.slice(0, excess) : [] };
+}
+
 export async function create(input: CreateInput): Promise<LspClient> {
   const diagnosticsDebounceMs = input.diagnosticsDebounceMs ?? clientDefaults.diagnosticsDebounceMs;
   const diagnosticsDocumentWaitTimeoutMs =
@@ -655,24 +716,29 @@ export async function create(input: CreateInput): Promise<LspClient> {
     lruOrder.set(path, Date.now());
   };
 
-  /** 超过容量时淘汰最久未使用的文档（didClose 并移出驻留集合）。 */
+  /**
+   * 超过容量时淘汰最久未使用的文档（didClose 并移出驻留集合）。
+   *
+   * 单次有界遍历：容量是尽力而为的上限——等待诊断的文档要留到诊断收集完，可淘汰
+   * 项不足时就少淘汰（见 evictionPlan）。不要写成"跳过等待项再重试"的循环：等待
+   * 窗口内的文档可能占满驻留集合（例如某路径的等待尚未结束时它又被重新打开），
+   * 那时重试分支没有 await，等于同步自旋。
+   */
   async function evictExcess(): Promise<void> {
-    while (lruOrder.size > maxOpenDocuments) {
-      const oldest = lruOrder.keys().next().value;
-      if (oldest === undefined) return;
-      lruOrder.delete(oldest);
-      const document = files[oldest];
-      if (document === undefined) continue;
-      if (waitingForDiagnostics.has(oldest)) {
-        // 防御：等待中的文档挪到 MRU，等下轮再淘汰（正常不会发生，刚 touch 即 MRU）
-        touch(oldest);
-        continue;
-      }
+    const plan = evictionPlan({
+      order: [...lruOrder.keys()],
+      isResident: (path) => files[path] !== undefined,
+      isWaiting: (path) => waitingForDiagnostics.has(path),
+      maxOpenDocuments,
+    });
+    for (const path of plan.stale) lruOrder.delete(path);
+    for (const path of plan.evict) {
+      lruOrder.delete(path);
       await connection.sendNotification("textDocument/didClose", {
-        textDocument: { uri: pathToFileURL(oldest).href },
+        textDocument: { uri: pathToFileURL(path).href },
       });
-      delete files[oldest];
-      documentVersions.delete(oldest);
+      delete files[path];
+      documentVersions.delete(path);
     }
   }
 
@@ -1073,9 +1139,49 @@ export async function create(input: CreateInput): Promise<LspClient> {
     };
   };
 
-  const sendInspectRequest = async <T>(method: string, message: object): Promise<T> => {
+  /**
+   * 发一次可取消的请求：signal 中止时既通过 CancellationToken 让服务器停下
+   * （$/cancelRequest），也立刻以 signal.reason（默认 AbortError）拒绝本地
+   * promise——服务器可能永远不回应，工具调用不能就这么挂着。
+   */
+  async function sendAbortableRequest<T>(
+    method: string,
+    params: object,
+    signal: AbortSignal | undefined,
+  ): Promise<T> {
+    if (!signal) return await connection.sendRequest<T>(method, params);
+    if (signal.aborted) throw abortReason(signal);
+    const source = new CancellationTokenSource();
+    const aborted = Promise.withResolvers<never>();
+    // 中止可能恰好在请求已返回之后才触发：那时 race 已经结算，而这个 promise 的
+    // rejection 没人再看——提前挂一个空 catch，否则它会变成 unhandled rejection
+    // （pi 会因此整体退出）。
+    void aborted.promise.catch(() => {
+      /* 失败路径由 race 处理 */
+    });
+    const onAbort = (): void => {
+      source.cancel();
+      aborted.reject(abortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
     try {
-      return await retryOnContentModified(() => connection.sendRequest<T>(method, message));
+      return await Promise.race([
+        connection.sendRequest<T>(method, params, source.token),
+        aborted.promise,
+      ]);
+    } finally {
+      signal.removeEventListener("abort", onAbort);
+      source.dispose();
+    }
+  }
+
+  const sendInspectRequest = async <T>(
+    method: string,
+    message: object,
+    signal?: AbortSignal,
+  ): Promise<T> => {
+    try {
+      return await retryOnContentModified(() => sendAbortableRequest<T>(method, message, signal));
     } catch (error) {
       if (error instanceof ResponseError && error.code === LSP_METHOD_NOT_FOUND) {
         throw new LspMethodNotSupportedError(input.serverID, method);
@@ -1170,11 +1276,15 @@ export async function create(input: CreateInput): Promise<LspClient> {
       // 与编辑器行为一致。
       const referencesRequest = () =>
         retryOnContentModified(() =>
-          connection.sendRequest<{ uri: string }[] | null>("textDocument/references", {
-            textDocument: { uri },
-            position,
-            context: { includeDeclaration: true },
-          }),
+          sendAbortableRequest<{ uri: string }[] | null>(
+            "textDocument/references",
+            {
+              textDocument: { uri },
+              position,
+              context: { includeDeclaration: true },
+            },
+            request.signal,
+          ),
         );
 
       const toPaths = (locations: { uri: string }[] | null): Set<string> =>
@@ -1187,11 +1297,15 @@ export async function create(input: CreateInput): Promise<LspClient> {
       const sendRename = async (): Promise<WorkspaceEdit | null> => {
         try {
           return await retryOnContentModified(() =>
-            connection.sendRequest<WorkspaceEdit | null>("textDocument/rename", {
-              textDocument: { uri },
-              position,
-              newName: request.newName,
-            }),
+            sendAbortableRequest<WorkspaceEdit | null>(
+              "textDocument/rename",
+              {
+                textDocument: { uri },
+                position,
+                newName: request.newName,
+              },
+              request.signal,
+            ),
           );
         } catch (error) {
           if (error instanceof ResponseError && error.code === LSP_METHOD_NOT_FOUND) {
@@ -1206,10 +1320,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
         let prepared: PrepareRenameResponse | null;
         try {
           prepared = await retryOnContentModified(() =>
-            connection.sendRequest<PrepareRenameResponse | null>("textDocument/prepareRename", {
-              textDocument: { uri },
-              position,
-            }),
+            sendAbortableRequest<PrepareRenameResponse | null>(
+              "textDocument/prepareRename",
+              { textDocument: { uri }, position },
+              request.signal,
+            ),
           );
         } catch (error) {
           if (error instanceof ResponseError && error.code === LSP_METHOD_NOT_FOUND) {
@@ -1235,6 +1350,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
       let previous: Set<string> | undefined;
       let current = toPaths(locations);
       for (;;) {
+        request.signal?.throwIfAborted();
         const settled = previous !== undefined && samePaths(previous, current);
         const expired = Date.now() >= deadline;
         if (settled || expired) {
@@ -1259,34 +1375,40 @@ export async function create(input: CreateInput): Promise<LspClient> {
           // 继续轮询到重新收敛后再重发 rename 复检（预算耗尽则向上抛）。
         }
         previous = current;
-        await sleep(renameVerificationTiming.pollMs);
+        await sleepWithSignal(renameVerificationTiming.pollMs, request.signal);
         current = toPaths(await referencesRequest());
       }
     },
     async definition(request: InspectPositionRequest): Promise<InspectLocation[]> {
       const { uri, position } = await preparePositionRequest(request);
       return toInspectLocations(
-        await sendInspectRequest<DefinitionResult>("textDocument/definition", {
-          textDocument: { uri },
-          position,
-        }),
+        await sendInspectRequest<DefinitionResult>(
+          "textDocument/definition",
+          { textDocument: { uri }, position },
+          request.signal,
+        ),
       );
     },
     async references(request: InspectPositionRequest): Promise<InspectLocation[]> {
       const { uri, position } = await preparePositionRequest(request);
-      const locations = await sendInspectRequest<LspLocation[] | null>("textDocument/references", {
-        textDocument: { uri },
-        position,
-        context: { includeDeclaration: true },
-      });
+      const locations = await sendInspectRequest<LspLocation[] | null>(
+        "textDocument/references",
+        {
+          textDocument: { uri },
+          position,
+          context: { includeDeclaration: true },
+        },
+        request.signal,
+      );
       return toInspectLocations(locations);
     },
     async hover(request: InspectPositionRequest): Promise<Hover | null> {
       const { uri, position } = await preparePositionRequest(request);
-      return await sendInspectRequest<Hover | null>("textDocument/hover", {
-        textDocument: { uri },
-        position,
-      });
+      return await sendInspectRequest<Hover | null>(
+        "textDocument/hover",
+        { textDocument: { uri }, position },
+        request.signal,
+      );
     },
     get diagnostics() {
       const result = new Map<string, Diagnostic[]>();

package/src/lib/lsp/lsp.ts

@@ -965,6 +965,7 @@ export function createLspService(
           line: request.line,
           character: request.character,
           newName: request.newName,
+          signal: request.options?.signal,
         });
         return {
           serverID: client.serverID,
@@ -972,6 +973,8 @@ export function createLspService(
           ...(result.placeholder !== undefined && { placeholder: result.placeholder }),
         };
       } catch (error) {
+        // 调用方取消不是"服务器无法重命名"：直接向上抛
+        request.options?.signal?.throwIfAborted();
         failures.push({ serverID: client.serverID, error });
       }
     }
@@ -1006,7 +1009,12 @@ export function createLspService(
     }
     const failures: { serverID: string; error: unknown }[] = [];
     for (const client of clients) {
-      const position = { path: request.file, line: request.line, character: request.character };
+      const position = {
+        path: request.file,
+        line: request.line,
+        character: request.character,
+        signal: request.options?.signal,
+      };
       try {
         if (request.query === "hover") {
           const hover = await client.hover(position);
@@ -1022,6 +1030,8 @@ export function createLspService(
           locations,
         } as LspInspectResult<Q>;
       } catch (error) {
+        // 调用方取消不是"服务器失败"：直接向上抛，别折叠成 all-servers-failed
+        request.options?.signal?.throwIfAborted();
         failures.push({ serverID: client.serverID, error });
       }
     }

package/src/lib/lsp/rename-tool.ts

@@ -31,6 +31,7 @@ import {
   type AppliedFileEdit,
   canonicalizeEdit,
   expandWorkspaceEdit,
+  type LspPosition,
   symbolCandidates,
 } from "./rename.js";
 
@@ -117,7 +118,12 @@ export function registerLspRenameTool(
           `Symbol "${params.symbol}" not found on line ${params.line} of ${filePath}. Read the file again and locate the symbol.`,
         );
       }
-      const successes: { result: Awaited<ReturnType<typeof service.rename>> }[] = [];
+      // 探测结果必须与候选成对记录：失败的候选不会进 successes，若按下标去取，
+      // 后面的成功结果会被错配给前面的候选——消歧提示就会指向别的符号的列号。
+      const successes: {
+        candidate: LspPosition;
+        result: Awaited<ReturnType<typeof service.rename>>;
+      }[] = [];
       const notPossibleErrors: string[] = [];
       for (const candidate of candidates) {
         signal?.throwIfAborted();
@@ -130,7 +136,7 @@ export function registerLspRenameTool(
             newName: params.new_name,
             options: requestOptions,
           });
-          successes.push({ result });
+          successes.push({ candidate, result });
         } catch (error) {
           if (error instanceof RenameNotPossibleError) {
             notPossibleErrors.push(error.message);
@@ -150,15 +156,13 @@ export function registerLspRenameTool(
       // 同一符号的多次出现编辑集合一致；不一致即为不同符号 → 要求补 character
       const groups = new Map<
         string,
-        { result: (typeof successes)[number]["result"]; candidates: typeof candidates }
+        { result: (typeof successes)[number]["result"]; candidates: LspPosition[] }
       >();
-      for (const [index, candidate] of candidates.entries()) {
-        const entry = successes.at(index);
-        if (!entry) continue;
-        const key = canonicalizeEdit(entry.result.edit);
+      for (const { candidate, result: probe } of successes) {
+        const key = canonicalizeEdit(probe.edit);
         const group = groups.get(key);
         if (group) group.candidates.push(candidate);
-        else groups.set(key, { result: entry.result, candidates: [candidate] });
+        else groups.set(key, { result: probe, candidates: [candidate] });
       }
       if (groups.size > 1) {
         const listing = [...groups.values()]
@@ -191,6 +195,7 @@ export function registerLspRenameTool(
           absolutePath: fileEdit.path,
           change: { oldText: fileEdit.oldText, newText: fileEdit.newText },
           policy: options.policy,
+          signal,
         });
       }
 

package/src/lib/write-guard.ts

@@ -108,8 +108,16 @@ export interface WriteGuardContext {
   hasUI: boolean;
   abort?: () => void;
   ui?: {
-    select: (title: string, options: string[]) => Promise<string | undefined>;
-    input: (title: string, placeholder?: string) => Promise<string | undefined>;
+    select: (
+      title: string,
+      options: string[],
+      opts?: { signal?: AbortSignal },
+    ) => Promise<string | undefined>;
+    input: (
+      title: string,
+      placeholder?: string,
+      opts?: { signal?: AbortSignal },
+    ) => Promise<string | undefined>;
   };
 }
 
@@ -123,6 +131,8 @@ export interface WriteGuardOptions {
   change?: PendingChange;
   /** 调用方所在扩展入口持有的非沙盒请求策略（跨入口一致时绑同一个 pi.events）。 */
   policy: RequestPolicy;
+  /** 工具调用的中止信号：透传给审批对话框，工具被取消时对话框一起关掉。 */
+  signal?: AbortSignal;
 }
 
 /**
@@ -165,14 +175,18 @@ export async function guardWriteAccess(
       (diffPreview ? `\n${diffPreview}\n` : "") +
       `\nAllow?`;
 
-    const choice = await ctx.ui.select(title, ["Approve once", "Block", "Block with reason"]);
+    const choice = await ctx.ui.select(title, ["Approve once", "Block", "Block with reason"], {
+      signal: opts.signal,
+    });
     if (choice === undefined) {
       ctx.abort?.();
       throw new Error(`user deny ${opts.toolName}: cancelled`);
     }
     if (choice === "Approve once") return;
     if (choice === "Block") throw new Error(`user deny ${opts.toolName}: blocked`);
-    const feedback = await ctx.ui.input("Why was this write denied?");
+    const feedback = await ctx.ui.input("Why was this write denied?", undefined, {
+      signal: opts.signal,
+    });
     if (feedback === undefined) continue;
     throw new Error(
       feedback ? `user deny ${opts.toolName}: ${feedback}` : `user deny ${opts.toolName}: blocked`,

package/src/opencode/files.ts

@@ -201,7 +201,7 @@ export interface LinePage {
  */
 export async function readLines(
   filePath: string,
-  opts: { offset: number; limit: number; maxBytes?: number },
+  opts: { offset: number; limit: number; maxBytes?: number; signal?: AbortSignal },
 ): Promise<LinePage> {
   if (opts.offset < 0) return readTailLines(filePath, opts);
   const start = opts.offset - 1;
@@ -216,6 +216,8 @@ export async function readLines(
   const rl = createInterface({ input: stream, crlfDelay: Infinity });
   try {
     for await (const text of rl) {
+      // 大文件的全量扫描可能持续数秒：每行检查一次取消，别等到读完才响应
+      opts.signal?.throwIfAborted();
       count += 1;
       if (count <= start) continue;
 
@@ -250,7 +252,7 @@ export async function readLines(
  */
 async function readTailLines(
   filePath: string,
-  opts: { offset: number; limit: number; maxBytes?: number },
+  opts: { offset: number; limit: number; maxBytes?: number; signal?: AbortSignal },
 ): Promise<LinePage> {
   const windowSize = -opts.offset;
   const window: string[] = [];
@@ -261,6 +263,7 @@ async function readTailLines(
   const rl = createInterface({ input: stream, crlfDelay: Infinity });
   try {
     for await (const text of rl) {
+      opts.signal?.throwIfAborted();
       count += 1;
       const line =
         text.length > MAX_LINE_LENGTH ? text.slice(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX : text;
@@ -279,6 +282,7 @@ async function readTailLines(
   let cut = false;
   let more = false;
   for (const line of window.slice(head)) {
+    opts.signal?.throwIfAborted();
     if (raw.length >= opts.limit) {
       more = true;
       break;
@@ -467,6 +471,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
       const page = await readLines(absolutePath, {
         offset: effectiveOffset,
         limit: limit ?? DEFAULT_MAX_LINES,
+        signal,
       });
 
       if (page.count < page.offset && !(page.count === 0 && page.offset === 1)) {
@@ -571,6 +576,7 @@ function registerEditTool(
         absolutePath,
         change: { oldText: oldString, newText: newString, replaceAll },
         policy,
+        signal,
       });
 
       const [message, details, diagnostics] = await withFileMutationQueue(
@@ -718,6 +724,7 @@ function registerWriteTool(
         absolutePath,
         change: { oldText: "", newText: content },
         policy,
+        signal,
       });
       const dir = dirname(absolutePath);
 

package/src/opencode/question.ts

@@ -110,7 +110,11 @@ function dialogTitle(q: Question): string {
   return q.header ? `${q.header}: ${q.question}` : q.question;
 }
 
-async function askSingle(q: Question, ctx: ExtensionContext): Promise<Answer> {
+async function askSingle(
+  q: Question,
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+): Promise<Answer> {
   const title = dialogTitle(q);
   const result = await selectWithOptionalInput(
     title,
@@ -119,17 +123,22 @@ async function askSingle(q: Question, ctx: ExtensionContext): Promise<Answer> {
       { label: CUSTOM_LABEL, inputPrompt: "Type your answer…" },
     ],
     ctx.ui,
+    { signal },
   );
   if (result === undefined) return [];
   return result.prompted ? (result.input ? [result.input] : []) : [result.label];
 }
 
-async function askMultiple(q: Question, ctx: ExtensionContext): Promise<Answer> {
+async function askMultiple(
+  q: Question,
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+): Promise<Answer> {
   const selected = await selectMultiple(
     dialogTitle(q),
     q.options.map((o) => ({ label: o.label })),
     ctx.ui,
-    { doneLabel: DONE_LABEL },
+    { signal, doneLabel: DONE_LABEL },
   );
   return selected;
 }
@@ -145,7 +154,7 @@ export default function question(pi: ExtensionAPI) {
     // 交互式提问不能与其他工具并行弹出，逐个串行执行
     executionMode: "sequential",
 
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       if (!ctx.hasUI) {
         throw new Error("Cannot ask questions: interactive UI is not available in this mode");
       }
@@ -153,7 +162,11 @@ export default function question(pi: ExtensionAPI) {
 
       const answers: Answer[] = [];
       for (const q of questions) {
-        answers.push(q.multiple ? await askMultiple(q, ctx) : await askSingle(q, ctx));
+        // 每个问题前检查一次：上一轮对话框期间被取消时不再弹下一个
+        signal?.throwIfAborted();
+        answers.push(
+          q.multiple ? await askMultiple(q, ctx, signal) : await askSingle(q, ctx, signal),
+        );
       }
 
       return {

package/src/spawn-agent.ts

@@ -532,7 +532,8 @@ export default function spawnAgent(pi: ExtensionAPI) {
     name: "spawn-agent",
     label: "spawn-agent",
     description: [
-      "Delegate a task to a subagent running in a separate pi process with an isolated context window.",
+      "Delegate a task to a subagent that runs in an isolated session with its own context window, inside this pi process rather than a separate one.",
+      "The call blocks until the subagent finishes its turn; its final output comes back as the tool result.",
       "The `agent` parameter must be one of the available subagent types listed in the system prompt.",
       `Subagents run read-only (${DEFAULT_TOOLS.join(", ")}) unless the agent declares an explicit toolset.`,
     ].join(" "),

package/src/talk/core.ts

@@ -148,6 +148,8 @@ export class TalkCore {
   private sweeper: ReturnType<typeof setInterval> | undefined;
   private initialDrain: ReturnType<typeof setTimeout> | undefined;
   private lastDeliveryFailureAt = 0;
+  /** 已上报故障的后台动作名；成功一次后移除，允许再次上报（见 runInBackground）。 */
+  private readonly backgroundFailuresReported = new Set<string>();
 
   constructor(options: TalkCoreOptions) {
     this.storage = options.storage;
@@ -168,11 +170,18 @@ export class TalkCore {
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
   async start(self: AgentRecord): Promise<void> {
-    await this.storage.init();
     // Record the process start time so presence can rule out pid reuse later.
     const pidStart = readStartTime(self.pid);
     this.self = pidStart === undefined ? self : { ...self, pidStart };
-    await writeRecord(this.storage, this.self);
+    try {
+      await this.storage.init();
+      await writeRecord(this.storage, this.self);
+    } catch (error) {
+      // 注册失败不是致命错误：本进程的 talk 工具照常可用，只是对等方看不到本
+      // agent。调用方（pi 的 session_start 回调）是 fire-and-forget，抛出去就是
+      // unhandled rejection，pi 会整体退出。
+      this.notifyBackgroundFailure("registration", error);
+    }
     try {
       await sweep(this.storage, this.now());
     } catch {
@@ -181,13 +190,13 @@ export class TalkCore {
     this.startInboxPoll();
     // Reclaim dead records periodically, not just at startup.
     this.sweeper = setInterval(() => {
-      void sweep(this.storage, this.now());
+      this.runInBackground("record sweep", () => sweep(this.storage, this.now()));
     }, SWEEP_INTERVAL_MS);
     this.sweeper.unref();
     // Drain mail queued while offline — deferred: delivering during
     // session_start races the agent's own first turn.
     const initial = setTimeout(() => {
-      void this.checkInbox();
+      this.runInBackground("inbox poll", () => this.checkInbox());
     }, INITIAL_DRAIN_DELAY_MS);
     initial.unref();
     this.initialDrain = initial;
@@ -235,10 +244,38 @@ export class TalkCore {
     }
   }
 
+  /**
+   * 后台动作失败的上报：同一个动作只报一次（轮询间隔只有几秒，持续失败会刷屏），
+   * 该动作下次成功后再失败会重新上报。通知通道本身出错也不能逃逸。
+   */
+  private notifyBackgroundFailure(action: string, error: unknown): void {
+    if (this.backgroundFailuresReported.has(action)) return;
+    this.backgroundFailuresReported.add(action);
+    const detail = error instanceof Error ? error.message : String(error);
+    try {
+      this.events.notify(`talk: ${action} failed: ${detail}`);
+    } catch {
+      // 通知通道不可用（如陈旧会话）：无处上报，也绝不能让它变成 rejection
+    }
+  }
+
+  /**
+   * 后台动作的 fire-and-forget 包装：收件箱轮询、记录回收与 presence 监视都没有
+   * 调用方可以 await，rejection 逃逸出去就是 unhandled rejection —— pi 会因此整体
+   * 退出（LSP 扩展踩过同一个坑）。这类失败只上报，agent 继续运行。
+   */
+  private runInBackground(action: string, task: () => Promise<void>): void {
+    void task()
+      .then(() => this.backgroundFailuresReported.delete(action))
+      .catch((error: unknown) => {
+        this.notifyBackgroundFailure(action, error);
+      });
+  }
+
   private startInboxPoll(): void {
     if (this.inboxPoll) return;
     this.inboxPoll = setInterval(() => {
-      void this.checkInbox();
+      this.runInBackground("inbox poll", () => this.checkInbox());
     }, INBOX_POLL_MS);
     this.inboxPoll.unref();
   }
@@ -752,7 +789,7 @@ export class TalkCore {
   private startWatchPoller(): void {
     if (this.watchPoller) return;
     this.watchPoller = setInterval(() => {
-      void this.pollWatched();
+      this.runInBackground("presence watch", () => this.pollWatched());
     }, WATCH_POLL_MS);
     this.watchPoller.unref();
   }

package/src/talk/index.ts

@@ -187,7 +187,16 @@ export default function talk(pi: ExtensionAPI) {
       lastSeenAt: now,
       status: "idle",
     };
-    void core.start(self).then(() => refreshGroupStatus(ctx.ui));
+    // core.start 内部的注册失败会自己上报（见 core.ts 的 notifyBackgroundFailure）；
+    // 这里再兜一层：这是 fire-and-forget 调用，没有任何调用方 await，rejection
+    // 逃逸出去就是 unhandled rejection，pi 会整体退出。
+    void core
+      .start(self)
+      .then(() => refreshGroupStatus(ctx.ui))
+      .catch(() => {
+        // 注册失败由 core 上报，refreshGroupStatus 内部也有 try/catch；
+        // 这里只保证不再抛（含会话已切走时 ctx 变 stale 的情况）
+      });
   });
 
   pi.on("agent_start", () => core.setWorking());

package/src/web/fetch.ts

@@ -343,7 +343,12 @@ export default function webFetchTool(pi: ExtensionAPI): void {
       // 落盘位置的审批与写文件工具同一套：工作区与 /tmp 自动放行，其余问用户。
       // 放在 try 外面，拒绝的原因（user deny）不该被改写成「抓取失败」。
       if (destination !== undefined) {
-        await guardWriteAccess(ctx, { toolName: "web_fetch", absolutePath: destination, policy });
+        await guardWriteAccess(ctx, {
+          toolName: "web_fetch",
+          absolutePath: destination,
+          policy,
+          signal,
+        });
       }
 
       try {