@trim21/personal-pi-extensions 0.1.509 → 0.1.511

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.509",
+  "version": "0.1.511",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -100,6 +100,7 @@
   "dependencies": {
     "@cortexkit/aft-bridge": "0.55.0",
     "@mozilla/readability": "^0.6.0",
+    "@parcel/watcher": "^2.6.0",
     "@vscode/tree-sitter-wasm": "^0.3.1",
     "jsonc-parser": "^3.3.1",
     "linkedom": "^0.18.0",

package/src/lib/lsp/adapter.ts

@@ -1,14 +1,13 @@
 /**
  * LSP 服务器插件契约：每个语言服务器一个 adapter class，向管理器提供统一接口。
  *
- * - findRoot 返回 undefined 表示该文件不应启用此服务器（目录外 / 无项目标记）；
+ * - root 由管理器按 workingDir 计算（缺省调用 cwd）；文件必须位于 root 之内
+ *   且命中 include（未配置时全匹配）才会由该服务器处理；
  * - spawn 返回 undefined 表示服务器不可用（二进制未安装）。
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import { dirname, join } from "node:path";
-
-import { exists, walkUp } from "./bin.js";
+import { resolve } from "node:path";
 
 export interface LspServerHandle {
   process: ChildProcessWithoutNullStreams;
@@ -29,27 +28,21 @@ export interface LspServerAdapter {
   readonly kind?: ServerKind;
   /** 关联的文件扩展名（含点，小写）；空数组表示匹配所有文件。 */
   readonly extensions: readonly string[];
+  /**
+   * 文件 glob（相对 root 或调用 cwd）；缺省/空 = 匹配所有文件。
+   * 过滤在管理器的 client 匹配阶段完成，adapter 不再持有 findRoot。
+   */
+  readonly include?: readonly string[];
+  /** 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即 cwd。 */
+  readonly workingDir?: string;
   /** per-server initialize 握手超时（ms）；缺省用全局配置 / client 默认。 */
   readonly startupTimeoutMs?: number;
   /** per-server 诊断等待时长（ms）；缺省用全局配置 / client 默认。 */
   readonly diagnosticsWaitMs?: number;
-  findRoot(file: string, cwd: string): Promise<string | undefined>;
   spawn(root: string, cwd: string): Promise<LspServerHandle | undefined>;
 }
 
-/**
- * 从文件所在目录向上（到 cwd）找项目标记文件；找不到时返回 cwd（opencode 的
- * NearestRoot 宽松语义，保证项目内文件至少有一个 root）。
- */
-export function nearestRoot(
-  markers: readonly string[],
-  file: string,
-  cwd: string,
-): Promise<string> {
-  for (const dir of walkUp(dirname(file), cwd)) {
-    for (const marker of markers) {
-      if (exists(join(dir, marker))) return Promise.resolve(dir);
-    }
-  }
-  return Promise.resolve(cwd);
+/** 计算服务器 root：workingDir 未配置时即调用 cwd，否则相对 cwd 解析（绝对路径原样）。 */
+export function serverRoot(workingDir: string | undefined, cwd: string): string {
+  return workingDir === undefined ? cwd : resolve(cwd, workingDir);
 }

package/src/lib/lsp/lsp.ts

@@ -9,7 +9,8 @@
  *   合并结果解析为 `ResolvedLspConfig`（缺省值应用、超时换算为 ms、白名单转
  *   Set），消费方不接触"未配置"歧义；
  *   没有内置默认服务器，所有服务器均须在配置里定义；
- *   配置在每个工具的调用 cwd 下惰性读取；enabled 引用不存在的服务器 id
+ *   配置在 session_start 预读并按 cwd 缓存，cwd 变化或 /lsp-reload 时重读；
+ *   schema 外的未知字段以 warning 上报。enabled 引用不存在的服务器 id
  *   是配置错误：全局配置在扩展加载（createLspService）时抛错，本地配置在
  *   session 开始预加载时通知，工具调用时校验抛错兜底。disabled 中未注册
  *   的 id 直接忽略；
@@ -29,7 +30,7 @@ import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 import type { Hover, WorkspaceEdit } from "vscode-languageserver-types";
 
-import { type LspServerAdapter } from "./adapter.js";
+import { type LspServerAdapter, serverRoot } from "./adapter.js";
 import {
   clientDefaults,
   create,
@@ -45,6 +46,7 @@ import {
 import { report } from "./diagnostic.js";
 import {
   createAdapters,
+  matchesInclude,
   mergeServerRecords,
   type ServerConfig,
   serverConfigSchema,
@@ -197,11 +199,35 @@ function isMissingFile(error: unknown): boolean {
   return (error as { code?: unknown }).code === "ENOENT";
 }
 
+/**
+ * 收集 schema 之外的未知字段警告（typebox 不校验 additionalProperties，
+ * 未知键会静默存活在解析结果里，这里显式报告避免配置写错无感知）。
+ */
+function unknownFieldWarnings(config: LspConfig, filePath: string): string[] {
+  const warnings: string[] = [];
+  const check = (record: object, known: Record<string, unknown>, scope: string): void => {
+    for (const key of Object.keys(record)) {
+      if (!(key in known)) warnings.push(`${filePath}${scope}: unknown field "${key}" ignored`);
+    }
+  };
+  check(config, lspConfigSchema.properties, "");
+  if (config.watch) check(config.watch, watchConfigSchema.properties, " watch");
+  for (const [id, server] of Object.entries(config.servers ?? {})) {
+    check(server, serverConfigSchema.properties, ` (server "${id}")`);
+  }
+  return warnings;
+}
+
 /** 读取并解析单个配置文件；文件不存在视为空配置，JSON / typebox 校验错误直接抛出。 */
-async function readConfigFile(filePath: string): Promise<LspConfig> {
+async function readConfigFile(
+  filePath: string,
+  onWarning?: (message: string) => void,
+): Promise<LspConfig> {
   try {
     const raw = await readFile(filePath, "utf8");
-    return Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
+    const config = Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
+    for (const message of unknownFieldWarnings(config, filePath)) onWarning?.(message);
+    return config;
   } catch (error) {
     if (isMissingFile(error)) return {};
     throw error;
@@ -209,10 +235,12 @@ async function readConfigFile(filePath: string): Promise<LspConfig> {
 }
 
 /** 同步版 readConfigFile（扩展加载时校验全局配置用）。 */
-function readConfigFileSync(filePath: string): LspConfig {
+function readConfigFileSync(filePath: string, onWarning?: (message: string) => void): LspConfig {
   try {
     const raw = readFileSync(filePath, "utf8");
-    return Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
+    const config = Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
+    for (const message of unknownFieldWarnings(config, filePath)) onWarning?.(message);
+    return config;
   } catch (error) {
     if (isMissingFile(error)) return {};
     throw error;
@@ -267,14 +295,15 @@ export function mergeConfig(globalConfig: LspConfig, localConfig: LspConfig): Ls
   };
 }
 
-/** 读取全局 + 本地配置，合并并解析为生效配置。 */
+/** 读取全局 + 本地配置，合并并解析为生效配置；未知字段警告经 onWarning 上报。 */
 export async function loadLspConfig(
   cwd: string,
   globalConfigPath: string = join(homedir(), ".pi", "agent", "lsp.json"),
+  onWarning?: (message: string) => void,
 ): Promise<ResolvedLspConfig> {
   const [globalConfig, localConfig] = await Promise.all([
-    readConfigFile(globalConfigPath),
-    readConfigFile(join(cwd, ".pi", "lsp.json")),
+    readConfigFile(globalConfigPath, onWarning),
+    readConfigFile(join(cwd, ".pi", "lsp.json"), onWarning),
   ]);
   return resolveConfig(mergeConfig(globalConfig, localConfig));
 }
@@ -311,6 +340,10 @@ interface LspState {
   cwd: string | undefined;
   /** client → adapter 扩展名集合，fan-out 时按扩展名过滤。 */
   clientExtensions: Map<LspClient, readonly string[]>;
+  /** 缓存的生效配置（configCwd 一致时复用；cwd 变化或 reload 后重读）。 */
+  config: ResolvedLspConfig | undefined;
+  /** config 的加载 cwd。 */
+  configCwd: string | undefined;
 }
 
 /** 渲染 LSP status 文本的回调（传入 undefined 表示清除）。 */
@@ -426,6 +459,10 @@ export interface LspServiceStartupOptions {
   notifyIntervalMs?: number;
   /** 会话级通知：启动失败时主动上报，不依赖触发请求恰好携带 notify。 */
   notify?: ExtensionUIContext["notify"];
+  /** session_start 预读的生效配置：直接注入缓存，避免首个工具调用重复读盘。 */
+  initialConfig?: ResolvedLspConfig;
+  /** initialConfig 对应的 cwd。 */
+  initialCwd?: string;
 }
 
 export function createLspService(
@@ -453,10 +490,23 @@ export function createLspService(
     servers: new Map(),
     cwd: undefined,
     clientExtensions: new Map(),
+    config: startupOptions?.initialConfig,
+    configCwd: startupOptions?.initialCwd,
   };
 
   let renderStatus: StatusRenderer | undefined;
 
+  /** 配置缓存：同一 cwd 内复用；cwd 变化或 reload 清缓存后重读。 */
+  async function currentConfig(cwd: string): Promise<ResolvedLspConfig> {
+    if (state.config && state.configCwd === cwd) return state.config;
+    const config = await loadLspConfig(cwd, globalConfigPath, (message) =>
+      sessionNotify?.(message, "warning"),
+    );
+    state.config = config;
+    state.configCwd = cwd;
+    return config;
+  }
+
   // ── 工作区文件监听（watcher）───────────────────────────────────────────────
 
   let watcher: WorkspaceWatcher | undefined;
@@ -526,7 +576,7 @@ export function createLspService(
   /** 首个 client 建立 / 会话 cwd 变化时（重）建监听器；watch.enabled: false 时不启动。 */
   async function ensureWatcher(cwd: string, notify?: ExtensionUIContext["notify"]): Promise<void> {
     if (state.closing || state.disabled) return;
-    const config = await loadLspConfig(cwd, globalConfigPath);
+    const config = await currentConfig(cwd);
     const watch = config.watch;
     if (!watch.enabled) return;
     if (watcher && watcherCwd === cwd) return;
@@ -612,7 +662,7 @@ export function createLspService(
     }
     if (state.closing || state.disabled) return [];
     if (!containsPath(file, cwd)) return [];
-    const config = await loadLspConfig(cwd, globalConfigPath);
+    const config = await currentConfig(cwd);
     const timeout = {
       diagnosticsDebounceMs: config.diagnosticsDebounceMs,
       diagnosticsDocumentWaitTimeoutMs: config.diagnosticsDocumentWaitTimeoutMs,
@@ -633,8 +683,9 @@ export function createLspService(
     for (const adapter of active) {
       if (adapterFilter && !adapterFilter(adapter)) continue;
       if (adapter.extensions.length > 0 && !adapter.extensions.includes(extension)) continue;
-      const root = await adapter.findRoot(file, cwd);
-      if (!root) continue;
+      const root = serverRoot(adapter.workingDir, cwd);
+      if (!containsPath(file, root)) continue;
+      if (!matchesInclude(adapter.include ?? [], file, root, cwd)) continue;
       const key = root + adapter.id;
       const failedAt = state.brokenFailAt.get(key);
       if (failedAt !== undefined) {
@@ -925,6 +976,9 @@ export function createLspService(
 
   async function reload(serverID: string): Promise<void> {
     state.closing = true;
+    // 配置缓存失效：下次工具调用按当前 cwd 重新读盘，让配置修改生效
+    state.config = undefined;
+    state.configCwd = undefined;
     const targets = state.clients.filter((client) => client.serverID === serverID);
     await Promise.all(targets.map((client) => client.shutdown())).catch(() => {
       // 个别进程退出失败不阻止清理流程
@@ -1036,7 +1090,13 @@ export function createLspManager(
       service = undefined;
     }
     try {
-      const config = await loadLspConfig(ctx.cwd, options?.globalConfigPath);
+      const config = await loadLspConfig(ctx.cwd, options?.globalConfigPath, (message) => {
+        try {
+          ctx.ui.notify(message, "warning");
+        } catch {
+          /* 旧会话 ctx 已失效：通知无处可去 */
+        }
+      });
       validateConfig(config, options?.adapters);
       if (enabledServerCount(config, options?.adapters) === 0) return;
       // 下面两个闭包被 service 长期持有，可能在会话被替换或 reload 后仍触发
@@ -1053,6 +1113,9 @@ export function createLspManager(
             /* 旧会话 ctx 已失效或 UI 不可用：通知无处可去 */
           }
         },
+        // session_start 已读盘的配置直接注入缓存，首个工具调用无需重复读盘
+        initialConfig: config,
+        initialCwd: ctx.cwd,
       });
       // footer status 显示当前所有 LSP server 状态（无 UI 时不显示）
       next.attachStatus((text) => {

package/src/lib/lsp/server-config.ts

@@ -1,5 +1,5 @@
 /**
- * 配置驱动的 LSP 服务器：一份 JSON 配置定义一个语言服务器（bin/args/rootMarkers/
+ * 配置驱动的 LSP 服务器：一份 JSON 配置定义一个语言服务器（bin/args/workingDir/
  * languageId/超时等），替代为每个语言写一个 adapter class。
  *
  * 配置文件沿用 lsp.json（全局 ~/.pi/agent/lsp.json + 本地 <cwd>/.pi/lsp.json）：
@@ -7,6 +7,9 @@
  * 覆盖、新增 id、全局其余保留），之后受顶层 enabled/disabled 列表过滤。
  * 没有内置默认服务器：未配置 servers 时不启动任何服务器。
  *
+ * 不做向上查找项目根的猜测：root 即调用 cwd（或 per-server workingDir），
+ * 文件归属由「文件位于 root 之内」+ include glob 判定。
+ *
  * executable 发现统一由用户配置：bin 支持绝对路径 / 项目工作区
  * （node_modules/.bin、.venv/bin、venv/bin）/ PATH，不再内置各语言的
  * 特殊探测逻辑（tsserver 路径、venv python 等）。
@@ -20,12 +23,7 @@ import { promisify } from "node:util";
 import { minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 
-import {
-  type LspServerAdapter,
-  type LspServerHandle,
-  nearestRoot,
-  type ServerKind,
-} from "./adapter.js";
+import { type LspServerAdapter, type LspServerHandle, type ServerKind } from "./adapter.js";
 import { exists, findBinaryInWorkspace, which } from "./bin.js";
 import { spawnProcess } from "./launch.js";
 
@@ -34,13 +32,14 @@ export const serverConfigSchema = Type.Object({
   include: Type.Optional(Type.Array(Type.String())),
   /** 服务器类型：language（真语言服务器，缺省）或 linter（只实现 LSP 协议的 lint）。 */
   kind: Type.Optional(Type.Union([Type.Literal("language"), Type.Literal("linter")])),
-  /** 项目根标记文件（从文件目录向上查找）；缺省用调用 cwd 作为根。 */
-  rootMarkers: Type.Optional(Type.Array(Type.String())),
+  /**
+   * 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即 cwd。
+   * 文件必须位于该目录内才会由本服务器处理；spawn 工作目录与 rootUri 均用它。
+   */
+  workingDir: Type.Optional(Type.String()),
   /** 可执行文件：绝对路径、相对调用 cwd 的路径，或名字（项目工作区优先，PATH 兜底）。 */
   bin: Type.Optional(Type.String()),
   args: Type.Optional(Type.Array(Type.String())),
-  /** 启动工作目录，支持 {root} / {cwd} 模板；缺省 {root}。 */
-  cwd: Type.Optional(Type.String()),
   /**
    * 追加到子进程的环境变量。string 值支持 {root} / {cwd} 模板与 ${VAR} 引用；
    * {sh: [...]} 在启动时执行命令（argv 直接执行、不经 shell），stdout trim 后作为值，
@@ -173,7 +172,7 @@ async function resolveBinary(bin: string, root: string, cwd: string): Promise<st
  * 支持 `!` 否定模式排除；多 pattern 数组拆开判断（任意 positive 命中且
  * 不被任何 negative 排除），避免库对混合数组的语义差异。
  */
-function matchesInclude(
+export function matchesInclude(
   patterns: readonly string[],
   file: string,
   root: string,
@@ -196,11 +195,13 @@ function matchesInclude(
   return candidates.some((candidate) => matches(candidate));
 }
 
-/** 由配置构建的通用 adapter；include 精确过滤在 findRoot 完成，extensions 不设扩展名过滤。 */
+/** 由配置构建的通用 adapter；include 过滤在 lsp.ts 的 client 匹配阶段完成，extensions 不设扩展名过滤。 */
 export class ConfigAdapter implements LspServerAdapter {
   readonly id: string;
   readonly kind: ServerKind;
   readonly extensions: readonly string[] = [];
+  readonly include: readonly string[];
+  readonly workingDir: string | undefined;
   readonly startupTimeoutMs: number | undefined;
   readonly diagnosticsWaitMs: number | undefined;
   readonly config: ServerConfig;
@@ -209,27 +210,21 @@ export class ConfigAdapter implements LspServerAdapter {
     this.id = id;
     this.config = config;
     this.kind = config.kind ?? "language";
+    this.include = config.include ?? [];
+    this.workingDir = config.workingDir;
     this.startupTimeoutMs = config.startupTimeoutMs;
     this.diagnosticsWaitMs = config.diagnosticsWaitMs;
   }
 
-  findRoot(file: string, cwd: string): Promise<string | undefined> {
-    const root = nearestRoot(this.config.rootMarkers ?? [], file, cwd);
-    return root.then((resolved) =>
-      matchesInclude(this.config.include ?? [], file, resolved, cwd) ? resolved : undefined,
-    );
-  }
-
   async spawn(root: string, cwd: string): Promise<LspServerHandle | undefined> {
     const bin = this.config.bin;
     if (!bin) return undefined;
     const resolved = await resolveBinary(bin, root, cwd);
     if (!resolved) return undefined;
-    const spawnCwd = resolveTemplate(this.config.cwd ?? "{root}", root, cwd);
     const env = await resolveEnv(this.config.env, root, cwd);
     return {
       process: spawnProcess(resolved, this.config.args ?? [], {
-        cwd: spawnCwd,
+        cwd: root,
         env,
       }),
       initialization: interpolateEnvDeep(this.config.initializationOptions, {

package/src/lib/lsp/watcher.ts

@@ -1,25 +1,29 @@
 /**
- * 工作区文件监听器：单个递归 fs.watch + 去抖批量回调。
+ * 工作区文件监听器：@parcel/watcher 事件源 + 去抖批量回调。
  *
- * - 事件源用 `node:fs/promises` 的 `watch(dir, { recursive: true, signal })`，
- *   不引入 chokidar（与仓库"FS 一律用 node:fs/promises"约定一致）；
- * - create / delete / rename 在底层都表现为 `rename`，内容改动为 `change`，
- *   故 LSP 的 created / changed / deleted 类型由 `lstat` 判定；
+ * - 事件源用 @parcel/watcher（原生实现，Linux 正确管理 inotify 生命周期，
+ *   忽略目录不建 watch，事件已区分 create / update / delete），
+ *   映射为 LSP 的 created / changed / deleted；
+ * - parcel 不报告目标是否目录：非删除事件用 lstat 学习已知目录集合并丢弃
+ *   目录事件；删除事件据此标记 isDirectory，由上层对驻留文档补 deleted；
  * - 尾部去抖（缺省 300ms）合并短时洪峰，最长 flushMs（缺省 1s）强制清批；
  * - 内置忽略 `node_modules` / `.git` / `dist` / `build` / `.venv` / `venv` /
- *   `target` / `coverage`，配置可追加；
- * - 忽略列表同时下传给 `fs.watch` 的 `ignore` 选项做内核层排除（Node >= 24.14 /
- *   26 的 recursive watch 对命中路径不创建 inotify watch，避免大型 `.git` 等
- *   子树耗尽 watch 配额导致 ENOSPC 崩溃）；运行环境不支持时静默回退为事件层过滤；
+ *   `target` / `coverage`，配置可追加；忽略列表下传 parcel 的 `ignore`
+ *   选项做后端层排除（忽略目录不递归、不建 watch），事件层再用 minimatch
+ *   过滤一遍兜底语义差异；
  * - 单批超过 maxBatch（缺省 500）截断并回调 onTruncated 提示一次；
- * - 目录事件默认丢弃；目录被删除时上报（isDirectory: true），由上层对其中
- *   的驻留文档补 deleted 事件。监听器启动或运行期失败时调用 onError 降级，
- *   不抛错。
+ * - 目录事件默认丢弃；目录被删除时上报（isDirectory: true）。监听器启动或
+ *   运行期失败时调用 onError 降级，不抛错。
  */
 
-import { lstat, watch, type WatchOptions as FsWatchOptions } from "node:fs/promises";
-import { join, normalize, relative, sep } from "node:path";
+import { lstat } from "node:fs/promises";
+import { normalize, relative, sep } from "node:path";
 
+import {
+  type AsyncSubscription,
+  type Event as ParcelWatcherEvent,
+  subscribe,
+} from "@parcel/watcher";
 import { minimatch } from "minimatch";
 
 export type FileChangeType = "created" | "changed" | "deleted";
@@ -68,34 +72,6 @@ function isIgnored(path: string, dir: string, patterns: string[]): boolean {
   return patterns.some((pattern) => minimatch(candidate, pattern));
 }
 
-/**
- * 为内核层 `fs.watch` 的 `ignore` 选项派生 pattern：为每条「目录内容」形态的
- * glob（尾部为通配目录段）追加「目录本身」形态并去重——Node 内部按相对路径
- * 对每个子项逐一匹配，只给内容形态时忽略目录本身仍会建 watch。
- *
- * 与事件层 minimatch 的语义差异（Node 内部 matcher 固定 `matchBase: true`、
- * `nonegate: true`）：无斜杠 pattern 按 basename 匹配任意层级，`!` 否定在
- * 内核层不生效。内核层只会少产生事件，差异部分仍由事件层兜底。
- */
-function kernelIgnorePatterns(patterns: readonly string[]): string[] {
-  const derived = new Set<string>();
-  for (const pattern of patterns) {
-    derived.add(pattern);
-    if (pattern.endsWith("/**")) derived.add(pattern.slice(0, -3));
-  }
-  return [...derived];
-}
-
-/**
- * `ignore` 选项的运行时支持始于 Node 24.14 / 26，@types/node 24.x 尚未声明；
- * 同时需剔除 fs 模块 WatchOptions.encoding 中的 "buffer" 字面量，否则不可赋给
- * fs/promises watch 返回 string filename 的重载。
- */
-type FsWatchOptionsWithIgnore = Omit<FsWatchOptions, "encoding"> & {
-  encoding?: BufferEncoding;
-  ignore?: readonly string[];
-};
-
 /**
  * 启动对 dir 的递归监听。onBatch 收到去抖合并后的批次；stop 后不再回调。
  * 返回的 promise 只在监听器无法建立（目录不存在等）时 reject——运行期
@@ -109,12 +85,14 @@ export function watchWorkspace(
   const debounceMs = options?.debounceMs ?? 300;
   const flushMs = options?.flushMs ?? 1_000;
   const maxBatch = options?.maxBatch ?? 500;
-  const ignorePatterns = kernelIgnorePatterns([...DEFAULT_IGNORE, ...(options?.ignore ?? [])]);
-  const abort = new AbortController();
+  const ignorePatterns = [...DEFAULT_IGNORE, ...(options?.ignore ?? [])];
 
-  // 从 stat 成功事件学习已知目录，目录被删除时据此标记 isDirectory
+  // 从非删除事件学习已知目录，目录被删除时据此标记 isDirectory
   const seenDirectories = new Set<string>();
 
+  let stopped = false;
+  let subscription: AsyncSubscription | undefined;
+
   let pending: FileChange[] = [];
   let flushTimer: ReturnType<typeof setTimeout> | undefined;
   let maxTimer: ReturnType<typeof setTimeout> | undefined;
@@ -139,17 +117,14 @@ export function watchWorkspace(
   };
 
   const push = (change: FileChange): void => {
+    if (stopped) return;
     if (pending.length === 0) maxTimer = setTimeout(flush, flushMs);
     pending.push(change);
     if (flushTimer) clearTimeout(flushTimer);
     flushTimer = setTimeout(flush, debounceMs);
   };
 
-  const classify = async (
-    filename: string,
-    eventType: "rename" | "change",
-  ): Promise<FileChange | undefined> => {
-    const path = normalize(join(dir, filename));
+  const classify = async (path: string, type: FileChangeType): Promise<FileChange | undefined> => {
     if (path === dir) return undefined;
     let isDirectory = false;
     let exists = true;
@@ -161,50 +136,65 @@ export function watchWorkspace(
       exists = false;
       if (seenDirectories.delete(path)) isDirectory = true;
     }
-    if (eventType === "change") {
-      if (!exists) return { path, type: "deleted", isDirectory };
-      if (isDirectory) return undefined;
-      return { path, type: "changed", isDirectory };
-    }
-    // rename：创建 / 删除 / 移入移出
+    if (type === "deleted") return { path, type, isDirectory };
+    // 事件与 lstat 之间的竞态：目标已消失按删除处理
     if (!exists) return { path, type: "deleted", isDirectory };
     if (isDirectory) return undefined;
-    return { path, type: "created", isDirectory };
+    return { path, type, isDirectory };
   };
 
-  const consumer = (async () => {
-    try {
-      const watchOptions: FsWatchOptionsWithIgnore = {
-        recursive: true,
-        signal: abort.signal,
-        ignore: ignorePatterns,
-      };
-      const iterator = watch(dir, watchOptions);
-      for await (const event of iterator) {
-        if (!event.filename) continue;
-        const change = await classify(
-          event.filename,
-          event.eventType === "change" ? "change" : "rename",
-        );
+  const handleError = (error: unknown): void => {
+    if (stopped) return;
+    options?.onError?.(`workspace watcher failed for ${dir}: ${String(error)}`);
+  };
+
+  const handleEvents = (error: Error | null, events: ParcelWatcherEvent[]): void => {
+    if (error) {
+      handleError(error);
+      return;
+    }
+    void (async () => {
+      for (const event of events) {
+        if (stopped) return;
+        const path = normalize(event.path);
+        const type: FileChangeType =
+          event.type === "create" ? "created" : event.type === "update" ? "changed" : "deleted";
+        const change = await classify(path, type);
         if (!change) continue;
         if (isIgnored(change.path, dir, ignorePatterns)) continue;
         push(change);
       }
+    })();
+  };
+
+  async function startSubscription(): Promise<void> {
+    try {
+      subscription = await subscribe(dir, handleEvents, { ignore: ignorePatterns });
+      if (stopped) {
+        await subscription.unsubscribe();
+        subscription = undefined;
+      }
     } catch (error) {
-      if (abort.signal.aborted) return;
-      options?.onError?.(`workspace watcher failed for ${dir}: ${String(error)}`);
+      handleError(error);
     }
-  })();
+  }
+
+  const started = startSubscription();
 
   // 目录不存在 / 无权限等启动期问题在这里暴露，让调用方可以降级
   return lstat(dir).then(() => ({
     async stop(): Promise<void> {
-      abort.abort();
-      try {
-        await consumer;
-      } catch {
-        // 监听器已因 abort 正常退出
+      stopped = true;
+      clearTimers();
+      if (subscription) {
+        try {
+          await subscription.unsubscribe();
+        } catch {
+          // 订阅已失败或重复 stop
+        }
+        subscription = undefined;
       }
+      await started;
     },
   }));
 }