Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

23.6 KB
Raw Blame
/**
 * watch — daemon 端的 workdir 文件监听(P4)。
 *
 * 实现选型:Node 内建 `fs.watch(dir, { recursive: true })`。
 *  - 远端跑在 bundled Node(≥22)上,Linux(inotify 递归模拟)/ macOS(FSEvents)
 *    都原生支持 recursive;不引原生依赖(@parcel/watcher 的 prebuilt .node
 *    进不了 esbuild 单文件 bundle,这正是它留在 desktop 侧的原因)。
 *  - fs.watch 只报 'rename' | 'change' + 相对 filename:'rename' 不区分
 *    add/unlink,用一次 lstat 判存在性映射到 FileTreeEvent 的 add/unlink。
 *
 * 过滤(与 desktop 本地 watcher 同语义):
 *  - ignore matcher(.gitignore + builtin)兜底,file/dir 双查任一命中即丢;
 *  - `.xdt-tmp` 原子写中间产物直接丢(防前端 ghost row);
 *  - 50ms 窗口按 (type, relPath) coalesce,吸收 agent 批量写盘的事件风暴——
 *    消费端(desktop → renderer fetchDir)按父目录 refetch,重复事件只是
 *    浪费 IPC,合并无语义损失。
 *
 * 生命周期:per-workdir 单 watcher(重复 watchStart 幂等);stdin EOF /
 * watchStop 时 close。事件经注入的 emit 回调发 `fileTree` 帧。
 *
 * 注:自带过滤器(ignore matcher / .xdt-tmp)在 watchStart 时就固定下来,
 * 控制端改开关后需要先 watchStop 再 watchStart 才能换 matcher。
 *
 * 同一 workdir 会被**多个消费方**请求(desktop 的 SSH 文件浏览器、device-link
 * 的 fs-watch topic)。每个消费方用 consumerId 登记自己的过滤需求,watcher 取
 * 全部消费者的**可见性并集** —— 否则后到的一方(控制端默认隐藏)会把前一方的
 * reveal matcher 覆盖掉:desktop 仍列着 build / dist,它们的改动却永远没有
 * 事件。多推的帧由订阅端按各自视图忽略,代价远小于静默丢事件。任一消费者在,
 * watcher 就不拆;最后一个 stop 才关。选项变化由 start() / stop() 收敛。
 */

import { watch as fsWatch, promises as fs, type FSWatcher } from 'node:fs';
import path from 'node:path';
import {
  createEventIgnoreMatcher,
  loadIgnoreMatcher,
  scopedLogger,
  WATCH_ALWAYS_IGNORE,
  XDT_TMP_SUFFIX,
  type Matcher,
} from '@cindy/file-browser-core';

const log = scopedLogger('file-service/watch');

/**
 * 「即使开关打开也不推事件」的恒真层(node_modules / Library / VCS / OS 垃圾)。
 * 与 desktop 本地 watcher 的 PREFILTER_ALWAYS 同一份名单(单源:
 * file-browser-core 的 WATCH_ALWAYS_IGNORE),因为 fs.watch recursive 会把
 * 这些目录的事件照单全推上来 —— 没有这层兜底,`npm install` 或 Unity 导入会在
 * SSH + IPC 上打出一串与路径数同阶的 fileTree 帧。容器依赖 workdir,常量即可。
 */
const eventAlwaysIgnore = createEventIgnoreMatcher();

/**
 * `WATCH_ALWAYS_IGNORE` 的小写集合。
 *
 * 按段比较的本地判断必须折叠大小写,与 `ignore` 包(createEventIgnoreMatcher
 * 消费它,`ignorecase` 默认 true)的口径一致:大小写不敏感卷上 `NODE_MODULES` /
 * `library` 这类变体在开关打开时可见,若本地比较区分大小写,它们**自身**的事件
 * 会被恒真层吞掉,行陈旧到手动刷新(评审 P2)。
 */
const alwaysIgnoreNamesLower = new Set(
  (WATCH_ALWAYS_IGNORE as readonly string[]).map((name) => name.toLowerCase()),
);

/**
 * 路径是否落在「开关打开也永远不推事件」目录的**内部**(不含目录自身)。
 *
 * 为什么不直接问 eventAlwaysIgnore:`ignore` 的目录模式(`node_modules/`)同时
 * 匹配该目录自身与它全部后代,而这里要的只是后代 —— 开关打开时 node_modules /
 * Library 这一行就在树里,它自己被创建 / 删除 / 改名必须让父目录 refetch
 * (评审 P1:整条 rename 被吞掉的话,树会陈旧到手动刷新)。所以按路径段判断:
 * 除最后一段外任一段命中名单即为「内部」。
 */
function isInsideAlwaysIgnoredDir(relPath: string): boolean {
  const segments = relPath.split('/');
  for (let i = 0; i < segments.length - 1; i += 1) {
    if (alwaysIgnoreNamesLower.has(segments[i].toLowerCase())) return true;
  }
  return false;
}

/**
 * 路径是否是「开关打开也永远不推事件」目录的**自身**(node_modules / Library)。
 * 这些行在开关打开时就在树里(见 isInsideAlwaysIgnoredDir),而恒真层的`ignore`
 * 模式对自身也命中 —— 兜底那一行必须先把它排除掉,否则目录自身的 rename 又会被
 * 吞回去。
 */
function isAlwaysIgnoredDirItself(relPath: string): boolean {
  const last = relPath.slice(relPath.lastIndexOf('/') + 1);
  return alwaysIgnoreNamesLower.has(last.toLowerCase());
}

export interface RemoteFileTreeEvent {
  workdir: string;
  type: 'add' | 'change' | 'unlink';
  /** workdir-relative POSIX path */
  relPath: string;
}

interface WatchEntry {
  watcher: FSWatcher;
  matcher: Matcher;
  /** 建 watcher 时生效的过滤开关;变了要重建 matcher(fs.watch 本身不变)。 */
  hideMetaFiles: boolean;
  showIgnoredDirs: boolean;
  /** coalesce 缓冲:key = `${type}::${relPath}`。 */
  pending: Map<string, RemoteFileTreeEvent>;
  flushTimer: NodeJS.Timeout | null;
}

/** 决定 watcher 过滤行为的选项(不含 workdir)。 */
interface WatchFilterOptions {
  hideMetaFiles: boolean;
  showIgnoredDirs: boolean;
}

/** 一个消费者在某个 workdir 上的意图。 */
interface ConsumerIntent {
  /** 当前尝试的过滤需求(reconcile 与并集用这个)。 */
  options: WatchFilterOptions;
  /** 最近一次 reconcile **成功后**生效过的值;从没成功过是 null。
   *  失败回滚恢复到它 —— 不能快照「进入 start 时的前值」:同一 consumerId 的
   *  重叠 start 里,那个前值可能是另一个尚未提交、同样失败的尝试(评审 P1)。 */
  committed: WatchFilterOptions | null;
}

function normalizeWatchOptions(opts: {
  hideMetaFiles?: boolean;
  showIgnoredDirs?: boolean;
}): WatchFilterOptions {
  return { hideMetaFiles: opts.hideMetaFiles ?? true, showIgnoredDirs: opts.showIgnoredDirs === true };
}

function sameWatchOptions(a: WatchFilterOptions, b: WatchFilterOptions): boolean {
  return a.hideMetaFiles === b.hideMetaFiles && a.showIgnoredDirs === b.showIgnoredDirs;
}

const COALESCE_MS = 50;

/** watcher 报错后重建的退避参数:起点 / 上限 / 次数上限。 */
const RECONCILE_RETRY_BASE_MS = 500;
const RECONCILE_RETRY_MAX_MS = 8_000;
/** 退避指数的封顶档位:计数到这里后不再变大,转为固定 RECONCILE_RETRY_MAX_MS 重试。 */
const RECONCILE_RETRY_BACKOFF_CAP = 5;

export class WorkdirWatchManager {
  private readonly entries = new Map<string, WatchEntry>();
  /** 启动中的 workdir:has 判定与 entries.set 之间隔着 loadIgnoreMatcher 的
   *  await,并发 start(双窗口 / 重连 replay)会双双通过判定,各建一个原生
   *  watcher——事件双份、先建的那个 watchStop 够不着直到 daemon 退出。
   *  并发请求 piggyback 同一个启动 promise。 */
  private readonly starting = new Map<string, Promise<void>>();
  /** 启动窗口内收到 stop 的 workdir:startInner 完成时不装 watcher(装完即拆),
   *  否则快速开关文件浏览会留下无人再来 stop 的孤儿原生 watcher。 */
  private readonly stopDuringStart = new Set<string>();
  /** 每个 workdir 的消费者 → 它的意图(当前尝试 + 最近一次生效值)。watcher 只此
   *  一份,选项取全部消费者的可见性并集(见 effectiveOptions);start() / stop()
   *  每轮重读它收敛。 */
  private readonly desired = new Map<string, Map<string, ConsumerIntent>>();

  /** watcher 报错后的重建重试定时器与次数(退避 + 上限,见 scheduleReconcileRetry)。 */
  private readonly retryTimers = new Map<string, NodeJS.Timeout>();
  private readonly retryAttempts = new Map<string, number>();

  /** 没带 consumerId 的调用方(旧控制端 / 内部调用)归到这个默认消费者。 */
  private static readonly DEFAULT_CONSUMER = 'default';
  private readonly emit: (event: RemoteFileTreeEvent) => void;

  constructor(emit: (event: RemoteFileTreeEvent) => void) {
    this.emit = emit;
  }

  /** 幂等启动。matcher 加载失败 / fs.watch 抛错向上冒(RPC 返回 OPERATION_FAILED)。
   *  已存在同 workdir 的 watcher 时:过滤开关不同则重建(控制端改了「显示被忽略
   *  的目录」后无需先 stop,重启守护进程也不必同步状态)。 */
  async start(
    workdir: string,
    opts: { hideMetaFiles?: boolean; showIgnoredDirs?: boolean } = {},
    consumerId: string = WorkdirWatchManager.DEFAULT_CONSUMER,
  ): Promise<void> {
    const consumers = this.desired.get(workdir) ?? new Map<string, ConsumerIntent>();
    const attempted = normalizeWatchOptions(opts);
    consumers.set(consumerId, {
      options: attempted,
      committed: consumers.get(consumerId)?.committed ?? null,
    });
    this.desired.set(workdir, consumers);
    try {
      await this.reconcile(workdir);
      this.clearReconcileRetry(workdir); // 新意图已生效:旧的重试状态作废
      // 成功才记 committed:失败回滚只恢复到「真的生效过」的值。
      const settled = this.desired.get(workdir)?.get(consumerId);
      if (settled && settled.options === attempted) settled.committed = attempted;
    } catch (err) {
      // 启动失败:回滚**本次**写入的意图,否则 daemon 会留下一个「幽灵消费者」——
      // 控制端的失败处理只清本地注册、不会再发 watchStop(见 remote-watch.ts),
      // 之后别的消费者的可见性并集会被它抬高,最后一人 stop 时还会因它留下
      // 孤儿 watcher(评审 P1)。
      //
      // 恢复到 **committed** 而不是进入时快照:同一 consumerId 的重叠 start(双
      // 窗口启同一 workdir)里,快照可能是另一个尚未提交、同样失败的尝试 ——
      // 恢复它等于让失败注册复活,而下面 fire-and-forget 的 reconcile 会真给
      // 它建一个没人再 stop 的 watcher。没有 committed = 该 consumer 从未成功
      // 注册过,直接删。
      const current = this.desired.get(workdir)?.get(consumerId);
      if (current && current.options === attempted) {
        if (current.committed) {
          current.options = current.committed;
        } else {
          this.desired.get(workdir)?.delete(consumerId);
          if (this.desired.get(workdir)?.size === 0) this.desired.delete(workdir);
        }
      }
      // 回滚改变了并集,而且失败可能就在「选项变化 → closeEntry 拆掉旧 watcher →
      // startInner 失败」之后:原有消费者此刻没有 watcher。按恢复后的意图再收敛
      // 一次;这次也失败(挂载仍不可用)就走**带退避的重试** —— 只记日志会让原消费
      // 者静默失去直播,直到下一次显式 start / stop 或 daemon 重连(评审 P1)。
      void this.reconcile(workdir)
        .then(() => this.retryAttempts.delete(workdir))
        .catch((rerr) => {
          log.warn('watch reconcile after rollback failed', workdir, String(rerr));
          this.scheduleReconcileRetry(workdir);
        });
      throw err;
    }
  }

  /**
   * 收敛到「当前所有消费者的可见性并集」。为什么不直接 piggyback 启动中的
   * promise:启动窗口内到达的 stop 会给 stopDuringStart 打标记让那个 watcher
   * 自拆,而带新选项的 start 如果只是复用旧 promise,就会既丢掉新选项、又因为
   * 标记留下「没有 watcher」的空档(两个 RPC 都报 success)。这里每轮重读
   * desired,所以两种中途变化都在下一轮收敛。
   *
   * 终止性:每轮要么直接确认返回、要么推进一次真实的 startInner;desired 只会
   * 被更新的请求改写或被 stop 删除,并发调用者数量有限 —— 循环次数以此封顶。
   */
  private async reconcile(workdir: string): Promise<void> {
    for (;;) {
      const inflight = this.starting.get(workdir);
      if (inflight) {
        // 前一轮可能用了已被覆盖的旧选项,也可能因期间到来的 stop 自拆 ——
        // 都交给下一轮。它的失败由发起它的 caller 冒走,这里不吞也不重试。
        await inflight;
        continue;
      }
      const want = this.effectiveOptions(workdir);
      if (!want) {
        // 没有消费者了:watcher 不该活着。所有进入这里的路径(stop、回滚删掉
        // 最后一个消费者)都要维护这个不变量 —— 否则会留下没人再 stop 的孤儿
        // watcher(评审 P1 同类:回滚删注册后 fire-and-forget 的收敛不会再拆)。
        this.closeEntry(workdir);
        return;
      }
      const existing = this.entries.get(workdir);
      if (existing) {
        if (sameWatchOptions(existing, want)) return;
        // 选项变了:拆掉重建(不能走 stop(),它会撤销 desired)。重建前先转发
        // 合并窗口里的事件 —— 否则还在线的消费者会漏掉这一批(评审 P2)。
        this.closeEntry(workdir, { flushPending: true });
      }
      const run = this.startInner(workdir, want);
      this.starting.set(workdir, run);
      try {
        await run;
      } finally {
        this.starting.delete(workdir);
        this.stopDuringStart.delete(workdir);
      }
    }
  }

  /**
   * 全部消费者的可见性并集:任一消费者要看被忽略目录 / `.meta`,watcher 就得
   * 放行它们(推给各订阅端后由各自的视图忽略)。没有消费者时返回 null。
   */
  private effectiveOptions(workdir: string): WatchFilterOptions | null {
    const consumers = this.desired.get(workdir);
    if (!consumers || consumers.size === 0) return null;
    let showIgnoredDirs = false;
    let showMetaFiles = false;
    for (const intent of consumers.values()) {
      if (intent.options.showIgnoredDirs) showIgnoredDirs = true;
      if (!intent.options.hideMetaFiles) showMetaFiles = true;
    }
    return { showIgnoredDirs, hideMetaFiles: !showMetaFiles };
  }

  /**
   * watcher 报错后的收敛重试(退避封顶,不设总上限)。
   *
   * 为什么不能只 catch 一下:错误把 entry 拆掉后,如果紧接着的 reconcile 又失败
   * (远程挂载短暂不可用 / 目录正在被替换),消费者意图仍留在 desired、但已经
   * 没有 watcher,也没有任何定时器会再来收敛 —— SSH 连接没断的情况下,后续文件
   * 事件会永久停止,直到用户改开关或重挂载面板(评审 P2)。退避避免持续失败时
   * 形成紧密重建循环。
   *
   * 为什么退避到顶还要继续:挂载 / 权限故障持续超过退避窗口(约 15.5s)在真实
   * 环境里很常见(扩容挂载、目录正在被替换),此时不能永久放弃 —— 意图还在,
   * watcher 就必须最终建回来,否则故障恢复后事件永久静默、只能靠重挂面板救
   * (评审 P1)。封顶后按固定频率重试,单次只做一次 matcher 加载 + fs.watch,
   * 代价可忽略;消费者撤销由 clearReconcileRetry / stopAll 结束这个循环。
   */
  private scheduleReconcileRetry(workdir: string): void {
    if (this.retryTimers.has(workdir)) return;
    if (!this.desired.has(workdir)) return; // 期间消费者全撤了:不再重试
    const attempt = (this.retryAttempts.get(workdir) ?? 0) + 1;
    // 计数封顶:延迟计算不会越界,超限后转为固定频率重试。
    const capped = Math.min(attempt, RECONCILE_RETRY_BACKOFF_CAP);
    this.retryAttempts.set(workdir, capped);
    if (attempt === RECONCILE_RETRY_BACKOFF_CAP + 1) {
      log.warn('watch reconcile still failing, retrying at capped backoff', workdir);
    }
    const delay = Math.min(
      RECONCILE_RETRY_BASE_MS * 2 ** (capped - 1),
      RECONCILE_RETRY_MAX_MS,
    );
    const timer = setTimeout(() => {
      this.retryTimers.delete(workdir);
      void this.reconcile(workdir)
        .then(() => this.retryAttempts.delete(workdir))
        .catch((err) => {
          log.warn('watch reconcile retry failed', workdir, String(err));
          this.scheduleReconcileRetry(workdir);
        });
    }, delay);
    timer.unref?.();
    this.retryTimers.set(workdir, timer);
  }

  /** 清掉某个 workdir 的重试状态(stop / 新 start 成功时调用)。 */
  private clearReconcileRetry(workdir: string): void {
    const timer = this.retryTimers.get(workdir);
    if (timer) {
      clearTimeout(timer);
      this.retryTimers.delete(workdir);
    }
    this.retryAttempts.delete(workdir);
  }

  private async startInner(workdir: string, opts: WatchFilterOptions): Promise<void> {
    const matcher = await loadIgnoreMatcher(workdir, {
      hideMetaFiles: opts.hideMetaFiles,
      honorVcsIgnore: false,
      showIgnoredDirs: opts.showIgnoredDirs,
    });

    const entry: WatchEntry = {
      watcher: null as unknown as FSWatcher,
      matcher,
      hideMetaFiles: opts.hideMetaFiles,
      showIgnoredDirs: opts.showIgnoredDirs,
      pending: new Map(),
      flushTimer: null,
    };
    const watcher = fsWatch(workdir, { recursive: true }, (eventType, filename) => {
      // filename 偶发 null(平台边缘情况),无法定位目标 — 丢弃,聚焦刷新兜底。
      if (!filename) return;
      void this.handleRaw(workdir, entry, eventType, filename.toString());
    });
    watcher.on('error', (err) => {
      // watcher 挂了(权限 / 目录被删):拆掉**这个** entry,保留消费者意图并按
      // 剩余并集重建。不能走 stop(workdir) —— 那要挑一个 consumerId,而错误不是
      // 任何消费者的意图变化:拿默认 id 会删错人,reconcile 又看到同一个坏
      // entry 选项没变而原地返回,直播就静默冻结到手动改开关或 daemon 重启。
      log.warn('fs.watch error, dropping watcher', workdir, String(err));
      if (this.entries.get(workdir) !== entry) return; // 已被替换 / 停止:不碰新 entry
      // 报错前已入队的事件仍是真实事件:重建前先转发,不随旧 entry 丢弃(评审 P2)。
      this.closeEntry(workdir, { flushPending: true });
      // 就地收敛;失败(挂载短暂不可用 / 目录正在被替换)则带退避重试,直到成功
      // 或耗尽 —— 只记日志会让这个入口静默失效到用户改开关(评审 P2)。
      void this.reconcile(workdir)
        .then(() => this.retryAttempts.delete(workdir))
        .catch((rerr) => {
          log.warn('watch reconcile after error failed', workdir, String(rerr));
          this.scheduleReconcileRetry(workdir);
        });
    });
    entry.watcher = watcher;
    if (this.stopDuringStart.delete(workdir)) {
      // 启动期间来了 stop(调用方的登记已清,不会再发第二次 stop):当场拆掉。
      // 标记的清理归 reconcile 的 finally(成功 / 失败两条路径都走那里)。
      try {
        watcher.close();
      } catch {
        // already closed
      }
      log.info('watch start cancelled by stop during startup', workdir);
      return;
    }
    this.entries.set(workdir, entry);
    log.info('watch started', workdir);
  }

  stop(workdir: string, consumerId: string = WorkdirWatchManager.DEFAULT_CONSUMER): void {
    const consumers = this.desired.get(workdir);
    if (consumers) {
      consumers.delete(consumerId);
      if (consumers.size > 0) {
        // 还有别的消费者:按剩余并集收敛(可能收窄,需要重建 matcher)。这里是
        // sync 的 RPC handler,重建异步进行 —— RPC 语义是「撤销本消费者的
        // 需求」,不承诺 watcher 在返回前已重建完。失败要走带退避的**重试**:
        // 旧 watcher 此刻已经被拆了,只记日志会让剩下的消费者在挂载短暂不可用
        // 时永久失去实时事件,直到下一次显式 start / stop 或 daemon 重连
        // (评审 P2)。
        void this.reconcile(workdir)
          .then(() => this.retryAttempts.delete(workdir))
          .catch((err) => {
            log.warn('watch reconcile after partial stop failed', workdir, String(err));
            this.scheduleReconcileRetry(workdir);
          });
        return;
      }
      this.desired.delete(workdir);
    }
    this.clearReconcileRetry(workdir);
    // 撤销意图:收敛循环读到 desired 缺失即结束(piggyback 的新 start 会写回)。
    // 还在启动窗口:打标记让 startInner 完成时自拆(entries 里此刻还没有它)。
    if (this.starting.has(workdir)) this.stopDuringStart.add(workdir);
    this.closeEntry(workdir);
  }

  /** 把合并窗口里已经入队的事件立刻发出去(重建前保序转发用)。 */
  private flushPending(entry: WatchEntry): void {
    if (entry.flushTimer) {
      clearTimeout(entry.flushTimer);
      entry.flushTimer = null;
    }
    if (entry.pending.size === 0) return;
    const batch = [...entry.pending.values()];
    entry.pending.clear();
    for (const evt of batch) this.emit(evt);
  }

  /**
   * 拆掉已就位的 watcher。不碰 desired —— 选项变化重建时由调用方决定意图。
   *
   * `flushPending`:**重建**路径(选项变化 / watcher 报错后重建)要先转发合并
   * 窗口里的事件 —— 旧 entry 的 `pending` 随 entry 一起被丢的话,还活着的消费者
   * 会漏掉这次事件,文件树陈旧到同目录下一次事件或手动刷新(评审 P2)。
   * 最后一个消费者停止 / stopAll 不带这个旗标:那时事件已无人消费,直接丢。
   */
  private closeEntry(workdir: string, opts?: { flushPending?: boolean }): void {
    const entry = this.entries.get(workdir);
    if (!entry) return;
    this.entries.delete(workdir);
    if (opts?.flushPending) this.flushPending(entry);
    else if (entry.flushTimer) clearTimeout(entry.flushTimer);
    try {
      entry.watcher.close();
    } catch {
      // already closed
    }
    log.info('watch stopped', workdir);
  }

  stopAll(): void {
    // 全部意图撤销:启动中的 workdir 也要让收敛循环看到「没有 desired」而结束。
    this.desired.clear();
    for (const timer of this.retryTimers.values()) clearTimeout(timer);
    this.retryTimers.clear();
    this.retryAttempts.clear();
    for (const workdir of [...this.starting.keys()]) this.stopDuringStart.add(workdir);
    for (const workdir of [...this.entries.keys()]) this.closeEntry(workdir);
  }

  private async handleRaw(
    workdir: string,
    entry: WatchEntry,
    eventType: string,
    rawFilename: string,
  ): Promise<void> {
    const relPath = rawFilename.split(path.sep).join('/');
    if (relPath === '' || relPath.startsWith('..')) return;
    if (relPath.endsWith(XDT_TMP_SUFFIX)) return;
    /** matcher 不知道路径是 file 还是 dir,双查任一命中即丢(同 desktop watcher)。 */
    if (entry.matcher.ignores(relPath, false) && entry.matcher.ignores(relPath, true)) return;
    // 开关打开也永远不推的目录(node_modules / Library):只丢**内部**事件,
    // 目录自身的生命周期事件要留(见 isInsideAlwaysIgnoredDir)。
    if (isInsideAlwaysIgnoredDir(relPath)) return;
    // 兜底:BUILTIN_IGNORE_ALWAYS(.git / .DS_Store 之类,自身与后代都不显示)。
    // 但恒真忽略目录自身已在上一行放行,不能再被这里拦下。
    if (!isAlwaysIgnoredDirItself(relPath) && eventAlwaysIgnore.ignores(relPath, true)) return;

    let type: RemoteFileTreeEvent['type'];
    if (eventType === 'change') {
      type = 'change';
    } else {
      // 'rename' = add 或 unlink,lstat 判存在性。
      try {
        await fs.lstat(path.join(workdir, relPath));
        type = 'add';
      } catch {
        type = 'unlink';
      }
    }
    this.enqueue(entry, { workdir, type, relPath });
  }

  private enqueue(entry: WatchEntry, event: RemoteFileTreeEvent): void {
    entry.pending.set(`${event.type}::${event.relPath}`, event);
    if (entry.flushTimer) return;
    entry.flushTimer = setTimeout(() => {
      entry.flushTimer = null;
      this.flushPending(entry);
    }, COALESCE_MS);
    entry.flushTimer.unref?.();
  }
}