[Bug][Windows] skill-filesystem crashes dsh web when a custom skill root contains an inaccessible directory

[Apprentice-Geo]

问题描述

在 Windows 上，当 @deepseek-ai/dsh-skill-filesystem 配置 customSkillDirs 后，如果被监视的 Skill 目录中存在当前用户无法访问的子目录，dsh web 会因为 Chokidar 调用 realpath() 返回 EPERM 而整体退出。

我的配置为：

- id: skill-filesystem
  name: '@deepseek-ai/dsh-skill-filesystem'
  disabled: false
  config:
    includeDefaultRoots: false
    customSkillDirs:
      - D:/codes/skills

启动命令：

pnpm dsh web

启动过程中会先输出 Web URL：

dsh web: http://127.0.0.1:3080/?token=...
dsh web: opening the default browser

随后 skill-filesystem 扫描 Skill 目录时发生：

dsh: fatal load failure: Error: EPERM: operation not permitted, realpath 'D:\codes\skills\audio-transcribe\.pytest_cache'
    at async realpath (node:internal/fs/promises:1177:10)
    at async NodeFsHandler._addToNodeFs (.../chokidar/handler.js:591:45)

[ELIFECYCLE] Command failed with exit code 1.

复现情况

最初出错目录为：

D:\codes\skills\audio-transcribe\.pytest_cache

该目录本身存在：

Resolve-Path 'D:\codes\skills\audio-transcribe\.pytest_cache'
Get-Item -Force 'D:\codes\skills\audio-transcribe\.pytest_cache'

均能正常返回。

但无法读取 ACL：

PS> icacls 'D:\codes\skills\audio-transcribe\.pytest_cache'

D:\codes\skills\audio-transcribe\.pytest_cache: Access is denied.
Successfully processed 0 files; Failed processing 1 files

普通用户直接删除也会失败。

修复权限并删除该 .pytest_cache 后，再次启动 dsh web，随后在另一个 Skill 中出现完全相同的问题：

dsh: fatal load failure: Error: EPERM: operation not permitted, realpath 'D:\codes\skills\bili-audiosummary\.pytest_cache'
    at async realpath (node:internal/fs/promises:1177:10)
    at async NodeFsHandler._addToNodeFs (.../chokidar/handler.js:591:45)

[ELIFECYCLE] Command failed with exit code 1.

再次修复并删除：

D:\codes\skills\bili-audiosummary\.pytest_cache

之后 dsh web 可以正常启动。

因此目前至少在两个独立 Skill 目录中可以观察到相同的失败模式。

预期行为

customSkillDirs 中某个无关子目录不可访问时，不应该导致整个 dsh web 退出。

比较合理的行为可能包括：

• 跳过无法访问的目录并输出 warning；
• watcher 对单个目录的 EPERM 做错误隔离；
• 排除 .pytest_cache、__pycache__、.venv 等明显与 Skill 定义无关的生成目录。

关于 .pytest_cache 权限问题

这些无法访问的 .pytest_cache 是我 Windows 开发环境中已经存在一段时间的问题，在使用 Codex 开发时也曾多次遇到。

目前尚未确定这些目录的 ACL 为什么会变成不可访问状态，因此我不认为有足够证据说明这是 DSH 创建或破坏的。

本报告关注的问题仅是：

当 customSkillDirs 中存在一个无法 realpath() 的子目录时，dsh-skill-filesystem 会让整个 dsh web 发生 fatal load failure。

环境

• OS: Windows 11
• DSH: built from source
• Node.js: v24.14.1
• DSH commit: c36a83ff6bb95e3f82cf79f9be7c724270a8aa61

[argszero]

Reproduced — but the fatality is not where the report places it.

Thanks for the exact stack, the icacls output and the two-directory confirmation; that was enough to reproduce the crash. Two measurements change the diagnosis before the chain itself:

• @deepseek-ai/dsh-skill-filesystem passes no ignorePermissionErrors to chokidar.watch — the option block is persistent / ignoreInitial / depth / followSymlinks / atomic / awaitWriteFinish / usePolling / interval (packages/skill/skill-filesystem/src/index.ts:492-505) — so chokidar re-emits your EPERM as an error event. That half of your reading is exactly right.
• The provider already contains that error. The fatal comes from a promise chokidar itself creates and never handles, which no provider try/catch can reach.

The chain, including the escape point

1. handler.js:591 — await fsrealpath(path) rejects on <skill>\.pytest_cache. depth: 1 is deliberate, not sloppy: isRelevantWatchEvent matches <skill>/SKILL.md at segments.length === 2 (src/index.ts:662-679), so grandchildren are read on purpose.
2. _addToNodeFs catches it and passes it to chokidar._handleError, which re-emits it (index.js:552-562): emit('error') is suppressed only for ENOENT/ENOTDIR, or for EPERM/EACCES when ignorePermissionErrors is on.
3. The provider sees the first error before ready → readiness.reject(error) (src/index.ts:520-525) → the catch at :536-540 closes the watcher and rethrows. close() calls removeAllListeners() (index.js:419), so the watcher now has zero error listeners while sibling scans are still in flight.
4. Those siblings were suspended in await fsrealpath when that happened — the this.fsw.closed guard sits before that await (handler.js:581), not after it — so their EPERM lands afterwards, _handleError still calls emit('error'), and with no listener Node rethrows the same error object out of emit.
5. That throw happens inside async _addToNodeFs, and the call carrying it is fire-and-forget: this._addToNodeFs(path, initialAdd, wh, depth + 1) in the readdirp data listener (handler.js:488) — no await, no .catch. The rejection is unobserved.
6. installFailLoud's unhandledRejection handler prints dsh: fatal load failure: and exits 1.

Measurements

Fixture: 16 sibling skill directories, each with one inaccessible grandchild. The reproduction is Windows-shaped by construction — a local copy of chokidar 5.0.0 whose realpath rejects with the same object shape your build produces (code: 'EPERM', syscall: 'realpath', same message, same path) — because the escape path is chokidar's own code, not mine. The rejection is delayed 40 ms so sibling reads overlap; with a single failing entry nothing overlaps, the watcher is closed before the others are ever touched, and nothing dies (that matches your first single-directory run).

consumer	error events delivered	_handleError calls	unhandled rejections
provider as shipped (close on first error)	1	16	15
identical fixture, watcher left open	16	16	0
ignorePermissionErrors: true, no close	0	0	0
close, then re-attach a swallowing listener	1	16	0
close, then .catch on handler.js:488	1	16	0
close, then .catch on add()'s chain	1	16	15

Instrumenting _handleError shows the transition directly:

[handleError] EPERM s00/.pytest_cache listeners=1   <- delivered to the provider
[handleError] EPERM s01/.pytest_cache listeners=0   <- emitted into the void
[handleError] EPERM s02/.pytest_cache listeners=0   ...

Two consequences. First, the only difference between dying and surviving is whether a listener is still attached when the late errors land (arm 1 vs arm 2) — the provider's own isolation is not the missing piece. Second, the carrier is the unawaited recursive call: a .catch there removes 15/15 rejections, while patching add()'s handler-less Promise.all(...).then(...) removes none (it only awaits the depth-0 call, so it is a separate latent hole, not this one).

Why your line is a rejection, not an exception

At your commit c36a83ff6b, installFailLoud registered only unhandledRejection (:685) and printed ${err.stack} (:660) — which is why your output is the bare two-frame stack. On current master the rejection label is unchanged (the Web profile e2e tests match it), but an uncaught exception now reports fatal uncaught exception and util.inspect output that lists code / syscall / path. So those two frames are the error object's creation site; they say nothing about where it escaped — which is why the trace points at _addToNodeFs even though _addToNodeFs swallows the error.

Workaround until this is fixed

watch: false in the same skill-filesystem config block: chokidar is then never constructed (retainRoot / ensureWatcher, src/index.ts:357-382), so there is no scan to fail — at the cost of live skill reload. Repairing the ACLs works for the same reason (nothing fails to resolve).

Fix options, with what each one measures

• Provider, one line: pass ignorePermissionErrors: true. Measured: 0 emits, 0 rejections, and no rescan storm (33 realpath calls — identical to the shipped arm). Caveat, and it is one-directional: the option is coarse, so it silences EPERM/EACCES for the whole watcher. A genuinely unreadable root also goes quiet, and list() would report complete: true with no candidates. complete: false is what downgrades the collect cache and logs skill provider "filesystem" skipped (packages/skill/skill/src/index.ts:600-607), so that path trades a crash for a silently wrong "complete".
• Provider, narrower: keep an error listener alive across close() — e.g. re-attach a swallowing one after watcher.close() in closeWatcher (src/index.ts:594-601). Measured: 0 rejections, the first error still reaches handleWatcherError, and complete: false is preserved.
• Upstream chokidar 5 (the actual defect; either half alone is sufficient): close() must not leave a watcher listener-less while work is in flight — skip emit in _handleError when listenerCount(EV.ERROR) === 0, or stop calling removeAllListeners(); and handler.js:488 must be awaited or given a .catch.

On your three suggestions

"Watcher isolates a single directory's EPERM" is already implemented (handleWatcherError, src/index.ts:561-567) — the fatal never passes through provider code, so that layer cannot be where it is fixed. Excluding .pytest_cache/__pycache__/.venv by name does not close the class: any inaccessible subdirectory of a skill root does it, and the trigger is a permission failure rather than a name, so a name skip would be a separate feature.

One platform note for anyone re-testing: on macOS I could not reproduce this without the shim. A chmod 000 directory fails readdir but resolves through realpath, and in the nested scan readdirp absorbs that failure before _handleError is ever called (0 calls, 0 emits). The Windows shape — realpath failing on an ACL-denied directory — is what reaches chokidar's emit path, which is why this report is realpath-flavoured.

[Apprentice-Geo]

Thanks for the detailed reproduction and investigation.

I can follow the main conclusion, but some of the async/lifecycle details are beyond what I can confidently evaluate myself. The key point I take away is that the first EPERM is handled by the provider, while the fatal comes from later in-flight chokidar work after the watcher has been closed and its error listeners removed.

Thanks for narrowing this down and for providing both the workaround and possible fix directions.

[Apprentice-Geo]

补充信息（本机复验）

以下内容由本机运行的 DSH agent 在同一对话中自检得出。之前的失败现场见附图。

环境：Windows 11 · Node v24.14.1 · pnpm 11.7.0 · HEAD c36a83ff6bb95e3f82cf79f9be7c724270a8aa61 · @deepseek-ai/dsh-skill-filesystem 实际解析到 chokidar 5.0.0

一、与原报告一致的复验结果

1. commit 与栈帧可以对应：HEAD 即报告中的 c36a83ff，栈帧所指的 chokidar/handler.js:591 正是 await fsrealpath(path)。

2. 不可读目录仍然存在：本机当前仍有 6 个。provider 使用 depth: 1，实测会命中其中 2 个，均位于扫描范围内；其余 4 个更深，不会被当前 watcher 扫描到：

   D:\codes\skills\.cache\subtitle-creator-pytest-20260811
   D:\codes\skills\subtitle-creator\.pytest_cache
   

3. 从进程级错误处理来看，这次 fatal load failure 实际由 未处理的 Promise rejection 触发，而不是 provider 正常的“watcher 启动失败后降级为 warning”路径。

   dsh: fatal load failure: 在全仓只有一个产生点：packages/boot/app-boot/src/index.ts:660，对应的 handler 通过同文件约 :685 的 proc.on('unhandledRejection', handler) 注册。

二、对照实验

使用同一根目录和同一组选项，唯一变量是 watcher 是否存在 error 监听者：

实验	实测结果
A：存在 on('error')	2 次 ERROR_EVENT EPERM，随后 READY，exit 0
B：不存在 on('error')	2 次 UNHANDLED_REJECTION EPERM，watcher 未进入 ready
C：存在监听，并在首个 error 时 close() watcher	1 次 ERROR_EVENT，之后没有 rejection；未命中竞态窗口
D：增加 ignorePermissionErrors: true	无 error 事件，直接 READY，exit 0

因此，EPERM 本身不必然导致进程退出；当错误能够被 watcher 的 error listener 正常接收时，进程可以继续运行。

三、隔离启动实验

将 $DSH_HOME 整份复制到临时目录，通过 --patch 仅打开 host skill-filesystem row，不修改任何持久配置，然后实际运行：

dsh web --port 0 --no-open

结果：

• 服务能够正常监听并打印 URL；
• 全程没有出现 fatal；
• 与报告现场“打印 URL → opening the default browser → 随后 fatal”的日志时序相比，提示该问题可能与浏览器客户端连接后触发的 catalog 读取或相关生命周期时序有关，而不只是“目录不可读”这一静态条件。

尝试使用无头浏览器驱动客户端进一步复现时，networkidle 等待超时，因此未能可靠驱动客户端完成复现。

所以这一部分目前只能说明：

无客户端时未出现 fatal，而原现场的 fatal 出现在浏览器打开之后。

不能据此确定浏览器客户端或某一次 catalog 读取就是直接触发原因。

四、已确认的机制与可能的竞态窗口

Chokidar 在未启用 ignorePermissionErrors 时遇到 EPERM，会通过 watcher 发出 error 事件。

如果当时不存在 error listener，Node.js EventEmitter 对未处理的 'error' 会直接 throw。该异常发生在 Chokidar 的异步扫描流程中时，可能进一步成为 rejected Promise，最终逃逸为 unhandledRejection，由 DSH 的全局 handler 转换为：

dsh: fatal load failure: ...

本次检查还发现了一个可以确认存在的 error listener 缺失路径。

packages/skill/skill-filesystem/src/index.ts:514-517 中：

const signal = this.lifecycle.signal
if (signal.aborted) {
  await this.closeWatcher(handle)
  signal.throwIfAborted()
}

这里 watcher 已经通过 chokidar.watch() 创建，首次文件系统扫描也可能已经开始，但 watcher.on('error', onError) 尚未注册。

对 Chokidar FSWatcher 增加只读探针后得到：

--- dispose after 0 ms ---
  [probe] close() called; error listeners now = 0

--- dispose after 3 ms ---
  [probe] close() called; error listeners now = 1

0 ms 的情况确实会走到“watcher 已创建，但尚未注册 error listener 就被 close”的路径。

此外，Chokidar 的 close() 会移除 listener，而此前已经启动的 fsrealpath() 等异步文件系统操作可能仍然处于 in-flight 状态。

因此存在这样一种可能的竞态：

watcher 开始扫描
→ realpath 仍在进行
→ watcher 被 close，error listener 被移除
→ in-flight realpath 返回 EPERM
→ error 无 listener 接收
→ rejection 逃逸为 unhandledRejection
→ DSH 全局 handler 触发 fatal

需要强调：这个完整时序目前尚未被稳定复现。

它的各个前提已有独立实测支持，但还没有成功让 EPERM 精确落入这一时间窗口，因此目前应视为有证据支持的竞态假设，而不是已经确定的完整根因。

五、provider 已有的错误降级路径

skill-filesystem 对 watcher 启动失败本身已有降级处理：

• packages/skill/skill-filesystem/src/index.ts:189-194 会返回 { candidates, complete: false }；
• registry 在 packages/skill/skill/src/index.ts:602-608 会将 provider 错误降级为 warning。

因此，正常进入 provider 错误处理路径的 watcher 启动失败并不会导致整个进程退出。

当前值得关注的是：

如果 watcher 内部异步操作在 error listener 已不存在的窗口中失败，这条 rejection 可能无法被 provider 当前的错误处理路径接住，并最终到达进程级 unhandledRejection handler。

六、复验中没有稳定复现的部分

在相同不可读目录仍然存在的情况下，使用真实 provider 运行：

• 12 轮
• 每轮并发两次 ctx.skills.list()

结果：

TOTAL_UNHANDLED_REJECTIONS: 0

6 个 skill 均正常列出，进程保持存活。

因此，原先可以观察到的：

存在不可读子目录 → dsh web fatal

并不是一个稳定、必然发生的因果关系。

更准确地说，目前证据表明：

• 不可读目录提供了 EPERM 的触发条件；
• 正常存在 error listener 时，EPERM 可以被处理而不导致进程退出；
• watcher 生命周期中存在 listener 尚未注册或已经被移除的路径；
• 如果 EPERM 恰好发生在这一时序窗口内，可能逃逸为 unhandledRejection；
• 但该竞态窗口目前尚未被稳定复现。

针对该窗口共进行了约 40 次组合尝试，包括：

• 空载并发 12 轮；
• libuv 线程池拥塞 20 轮；
• 启动中途 dispose 时序 0 / 1 / 2 / 4 / 8 / 16 ms 各一组。

均没有让 EPERM 精确落入上述窗口。

因此，这部分目前仍属于基于源码、对照实验和生命周期探针得到的推断。

本机的现场证据仍是附图的启动崩溃终端输出：

[argszero]

Your A/B/D arms replicate the mechanism independently, and both open questions in your follow-up have a concrete answer: the boundary condition for the race (it needs two unreadable entries, not one), and where the browser actually enters the picture.

Your arm C: one unreadable entry cannot race

Arm C is the only one that disagrees with my measurements, and the difference is the entry count. The fatal needs a second failing realpath still in flight when the provider closes the watcher — with one entry there is nothing left to emit, so the race is unreachable by construction. Same fixture, same consumer logic, ten runs each:

unreadable entries in flight	resolver latency	fatal
1	0 ms	0 / 10
1	40 ms	0 / 10
2	0 ms	8 / 10
2	1 ms	10 / 10
2	40 ms	10 / 10
16	0 ms	10 / 10
2 — watcher never closed (control)	0 ms	0 / 10

So it is not a rare flake: two entries fire it 8 times out of 10 with no artificial latency at all, and the only row that survives is the one where nothing closes the watcher. The window is not a millisecond-scale gap — the close path (readiness.reject → await → close() → removeAllListeners()) runs in microtasks, while the sibling's rejection arrives from the fs threadpool in a later turn, so any concurrently in-flight sibling lands after it.

That also explains why the count matters on your machine: you measured 2 of the 6 unreadable directories inside the scan range. Two is exactly the minimum, and if arm C was run against a fixture with a single one — or one where the entries were visited strictly serially — it could not reproduce. Re-running arm C with two depth-1 unreadable directories should now reproduce it reliably; your own ACL-denied directories are enough, no shim required.

The browser is the trigger, not the cause

Your isolation run is right, and the reason is stronger than a timing correlation: the watcher is demand-driven, and the Web client is one of exactly two things that ever ask for the catalog. FileSystemSkillProvider.list() is only reached through ctx.skills.list(), and the only two production callers are:

• packages/client/ui-skill/src/client/index.ts:121 — the client's per-session skills/list fetch. It is prewarmed at composer scope birth (warm(session), declared as the "scope-birth prewarm hook (fire-and-forget)" in packages/client/ui-input-trigger/src/types.ts:202) — i.e. the moment the browser attaches to a session, which is what your log shows: URL printed, browser opened, then the fatal.
• packages/skill/tool-skill/src/index.ts:134 — the model invoking the skill tool.

With no client attached, no session scope is born, nobody calls skills/list, list() never runs, and no watcher is ever opened — so there is no realpath to fail. Your headless run is not "the crash needs the client to behave a certain way"; it is "without a client the failing code path is never entered". The client is the trigger; the defect stays where the trace is, in the unhandled chokidar promise after the provider closes a watcher with work still in flight.

This is also testable in one line: with the client attached, open the skills panel (or type / in the composer) and the provider mounts a watcher for that root — the same fatal follows, with no browser-lifecycle involvement beyond the fetch.

Recap of the fix surface

Unchanged from the earlier reply, and the near-determinism above is the reason the fix has to be structural rather than a narrower race window: pass ignorePermissionErrors: true, keep an error listener alive across close() (measured: 0 rejections, first error still logged, complete: false preserved), or fix chokidar itself — do not emit when listenerCount(EV.ERROR) === 0, and give handler.js:488 a .catch. watch: false in the same config block remains the workaround, since it removes the watcher entirely.

[Apprentice-Geo]

Thanks for following this through and confirming both the minimum reproduction condition and the client trigger path. That clears up the two parts I was still uncertain about.