fix(windows): stabilize native coverage watchers

.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: c824111cbd3d5f4126b0a383c99d0600b3e33ecf
-2026-08-08-native-windows-pull-request-ci.zh.md: 76e719d073669e4af551224ebf04bbf9284126a2
+2026-08-08-native-windows-pull-request-ci.md: a798aa906c2e22bceb021d1a95c081e9fa534d7c
+2026-08-08-native-windows-pull-request-ci.zh.md: 58fed00e1f324a8d61af179421c7bc5703c25678

.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md

@@ -22,6 +22,8 @@ The coverage follow-up then exercised the serial heavy suites on the native host
 
 The blocking coverage gate exposed two more fixture contracts that had never run on the native lane. The JSONL materialization fault now asserts the structured filesystem error code because the Windows durable-directory implementation owns an `ENOTDIR` code without copying it into human prose. The ACP teardown ladder now uses Node children instead of assuming a POSIX shell and asserts Windows' force-termination outcome rather than POSIX signal names; POSIX still proves the `SIGTERM` and `SIGKILL` tiers. Those suites load native bindings or own real process trees, so the Windows thread pool runs them in the existing fork-isolated project while still merging their coverage into the same per-file threshold.
 
+After the branch incorporated a newer `master`, the next native coverage run found the last uncatalogued watcher path and a stress-test budget. `skill-local` opened existing Chokidar roots with the configured spelling, so `%TEMP%` could still reach libuv through `C:\\Users\\RUNNER~1` while events used the long directory name; its root and ancestor modes now share the canonical watch-path contract, while discovery retains the configured path. The newly added 10,000-session descendant walk also exceeded Vitest's default timeout under Windows coverage instrumentation, so that unchanged stack-safety workload has an explicit twenty-second stress-test budget rather than a smaller depth or a platform skip.
+
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
 Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.

.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md

@@ -22,6 +22,8 @@ Status: implemented
 
 这项阻断覆盖率门禁又暴露出两项从未在原生通道上运行过的 fixture 契约。JSONL 实体化故障场景现在断言结构化文件系统错误码，因为 Windows 的持久目录实现拥有 `ENOTDIR` 错误码，却不会将其复制进人类可读文本。ACP（Agent Client Protocol）拆卸阶梯现在使用 Node 子进程，不再假定 POSIX shell，并断言 Windows 的强制终止结果而非 POSIX 信号名称；POSIX 仍会证明 `SIGTERM` 与 `SIGKILL` 两级。这些套件会加载原生绑定或拥有真实进程树，因此 Windows 线程池会让它们在现有的 fork 隔离项目中运行，同时仍将这些套件的覆盖率汇入同一项逐文件阈值。
 
+分支纳入更新的 `master` 后，下一次原生覆盖率运行发现了最后一条未纳入统一契约的 watcher 路径和一项压力测试预算。`skill-local` 曾以配置时的路径拼写打开现有 Chokidar 根，因此 `%TEMP%` 仍可能以 `C:\\Users\\RUNNER~1` 进入 libuv，而事件使用长目录名；现在它的根模式与祖先模式共用规范化监听路径契约，发现过程仍保留配置路径。新增的 10,000 会话后代遍历在 Windows 覆盖率插桩下还会超过 Vitest 默认超时，因此该栈安全工作负载保持原有规模并获得显式的 20 秒压力测试预算，而不是缩小深度或按平台跳过。
+
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture 通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
 受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。

packages/skill/skill-local/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/skill-local/README.md
-README.md: f85cc2e6fd0c32cb88f28a2914a03e22b3a20657
-README.zh.md: 9ee09938737237df9e97e517c1dd44b511b7f596
+README.md: 6d3d97ea34308ccc920d0b42c5a220dd7a9d6d73
+README.zh.md: 9948369774bc08a4ddbd4e518b53134ddd7c6882

packages/skill/skill-local/README.md

@@ -44,7 +44,7 @@ When `ctx.fs` is available, discovery lists roots through `ctx.fs.listDir`, read
 
 ## Catalog Change Detection
 
-Existing skill roots are watched with Chokidar. The provider observes direct bundle directory additions/removals, flat Markdown additions/removals, and direct `SKILL.md` additions/removals/changes; `change` exists to rediscover catalog frontmatter such as `name` and `description`. Changes below `references`, `scripts`, `assets`, or other bundle resources do not invalidate the catalog. Events delivered in the same microtask batch collapse to one provider invalidation.
+Existing skill roots are watched with Chokidar. Before opening a native watcher, the provider realpaths the existing root or ancestor and restores the next missing segment; discovery and diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form libuv events. The provider observes direct bundle directory additions/removals, flat Markdown additions/removals, and direct `SKILL.md` additions/removals/changes; `change` exists to rediscover catalog frontmatter such as `name` and `description`. Changes below `references`, `scripts`, `assets`, or other bundle resources do not invalidate the catalog. Events delivered in the same microtask batch collapse to one provider invalidation.
 
 A root that does not exist is followed from the nearest existing ancestor one missing path segment at a time. The next segment is probed with `fs.watchFile`; once `.agents`, `skills`, or the configured root appears, observation advances until Chokidar can attach to the real root. Root deletion reverses this process, so deleting and recreating an entire skills directory remains observable. Project-scoped watchers are bounded by `watchMaxProjects`; revisiting an evicted project reattaches observation during discovery.
 

packages/skill/skill-local/README.zh.md

@@ -44,7 +44,7 @@
 
 ## 目录变更检测
 
-现有 skill 根由 Chokidar 监视。提供方会观察直属 bundle 目录的添加／移除、平铺 Markdown 文件的添加／移除，以及直接 `SKILL.md` 的添加／移除／变更；`change` 事件用于重新发现 `name`、`description` 等目录 frontmatter。`references`、`scripts`、`assets` 或其他 bundle 资源下的变更不会使目录失效。同一微任务批次内送达的事件会合并为一次提供方失效。
+现有 skill 根由 Chokidar 监视。打开原生 watcher 前，提供方会对现有根或祖先执行 realpath 解析，并拼回下一个缺失路径段；发现与诊断仍保留配置路径，从而避免 Windows 在 libuv 内部混用 8.3 别名与长格式事件路径。提供方会观察直属 bundle 目录的添加／移除、平铺 Markdown 文件的添加／移除，以及直接 `SKILL.md` 的添加／移除／变更；`change` 事件用于重新发现 `name`、`description` 等目录 frontmatter。`references`、`scripts`、`assets` 或其他 bundle 资源下的变更不会使目录失效。同一微任务批次内送达的事件会合并为一次提供方失效。
 
 不存在的根会从最近的现有祖先开始，每次沿一个缺失路径段跟踪。系统使用 `fs.watchFile` 探测下一段；当 `.agents`、`skills` 或已配置的根出现后，观察会逐级推进，直至 Chokidar 可以附加到真实根。根删除时，该过程反向执行，因此删除再重建整个 skills 目录仍可被观察到。按项目划分的 watcher 数量受 `watchMaxProjects` 限制；再次访问已被驱逐的项目时，发现阶段会重新附加观察。
 

packages/skill/skill-local/src/index.ts

@@ -19,7 +19,7 @@ import z from 'schemastery'
 import type Schema from 'schemastery'
 import { parse as parseYaml } from 'yaml'
 import type { FileSystem, FsDirEntry, FsTarget } from '@deepseek-ai/dsh-fs'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import {
   BUNDLED_SKILL_RANK,
   isSkillName,
@@ -525,7 +525,7 @@ class SkillWatchManager {
       readiness.resolve(undefined)
     })
     for (const event of ['add', 'addDir', 'change', 'unlink', 'unlinkDir'] as const) {
-      watcher.on(event, (path) => { this.handleWatchEvent(state, event, path) })
+      watcher.on(event, (path) => { this.handleWatchEvent(state, mode, event, path) })
     }
     try {
       await readiness.promise
@@ -540,12 +540,14 @@ class SkillWatchManager {
 
   private handleWatchEvent(
     state: RootWatchState,
+    mode: Extract<RootWatchMode, { kind: 'root' }>,
     event: SkillWatchEvent,
     path: string,
   ): void {
-    if (this.closing || !isRelevantWatchEvent(state.root, event, resolve(path))) return
+    const target = resolve(path)
+    if (this.closing || !isRelevantWatchEvent({ ...state.root, path: mode.anchor }, event, target)) return
     this.queueInvalidation()
-    if (resolve(path) === state.root.path && event === 'unlinkDir') {
+    if (target === mode.anchor && event === 'unlinkDir') {
       state.unhealthy = true
       this.scheduleRewatch(state)
     }
@@ -625,11 +627,12 @@ async function resolveRootWatchMode(root: string): Promise<RootWatchMode> {
     try {
       const info = await stat(candidate)
       if (info.isDirectory()) {
-        if (candidate === root) return { kind: 'root', anchor: root }
+        const anchor = await canonicalizeWatchPath(candidate)
+        if (candidate === root) return { kind: 'root', anchor }
         const firstSegment = relative(candidate, root).split(sep)[0]
         /* v8 ignore next -- candidate is a strict ancestor of root. */
-        if (firstSegment === undefined || firstSegment.length === 0) return { kind: 'root', anchor: root }
-        return { kind: 'ancestor', anchor: candidate, nextPath: join(candidate, firstSegment) }
+        if (firstSegment === undefined || firstSegment.length === 0) return { kind: 'root', anchor }
+        return { kind: 'ancestor', anchor, nextPath: join(anchor, firstSegment) }
       }
     } catch (error) {
       /* v8 ignore next -- Non-absence stat failures are platform/permission-specific and propagate as incomplete discovery. */

packages/skill/skill-local/tests/skill-local-watcher.spec.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events'
 import type { Stats } from 'node:fs'
-import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { mkdir, realpath, rm, symlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
@@ -11,6 +11,7 @@ interface FakeWatcherControl {
   emitter: EventEmitter
   closeCalls: number
   options: Record<string, unknown>
+  path: string
 }
 
 interface FakeWatchFileControl {
@@ -63,9 +64,9 @@ vi.mock('node:fs/promises', async (importOriginal) => {
 
 vi.mock('chokidar', () => ({
   default: {
-    watch(_path: unknown, options: Record<string, unknown>) {
+    watch(path: unknown, options: Record<string, unknown>) {
       const emitter = new EventEmitter() as EventEmitter & { close(): Promise<void> }
-      const control: FakeWatcherControl = { emitter, closeCalls: 0, options }
+      const control: FakeWatcherControl = { emitter, closeCalls: 0, options, path: String(path) }
       emitter.close = async () => {
         control.closeCalls += 1
         if (watcherHarness.closeErrors > 0) {
@@ -114,6 +115,26 @@ beforeEach(() => {
 })
 
 describe('skill-local watcher failures', () => {
+  it('canonicalizes an existing root before opening its native watcher', async () => {
+    const target = await tempDir('skill-watch-canonical-target')
+    const aliasParent = await tempDir('skill-watch-canonical-alias')
+    const alias = join(aliasParent, 'alias')
+    await symlink(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    const root = join(alias, '.dsh/skills')
+    await writeSkill(root, 'canonical-skill')
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const fiber = await ctx.plugin(SkillLocal, {
+      dshHome: join(alias, '.dsh'),
+      agentsHome: join(alias, '.agents'),
+      watch: true,
+    })
+
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['canonical-skill'])
+    expect(watcherHarness.watchers[0]?.path).toBe(await realpath(root))
+    await fiber.dispose()
+  })
+
   it('ignores missing-path probes until the observed path actually changes', async () => {
     const home = await tempDir('skill-watch-missing-stable')
     const ctx = new Context()
@@ -205,24 +226,22 @@ describe('skill-local watcher failures', () => {
     const first = watcherHarness.watchers[0]
     if (first === undefined) throw new Error('expected a root watcher')
 
-    first.emitter.emit('change', join(root, 'notes.txt'))
+    first.emitter.emit('change', join(first.path, 'notes.txt'))
     first.emitter.emit('change', join(home, 'outside.md'))
-    first.emitter.emit('change', join(root, 'watched-skill/references.md'))
-    first.emitter.emit('change', join(root, '.system/SKILL.md'))
+    first.emitter.emit('change', join(first.path, 'watched-skill/references.md'))
+    first.emitter.emit('change', join(first.path, '.system/SKILL.md'))
     await settle()
     expect(invalidations).toBe(0)
 
-    first.emitter.emit('change', join(root, 'watched-skill/SKILL.md'))
-    first.emitter.emit('change', join(root, 'watched-skill/SKILL.md'))
+    first.emitter.emit('change', join(first.path, 'watched-skill/SKILL.md'))
+    first.emitter.emit('change', join(first.path, 'watched-skill/SKILL.md'))
     await settle()
     expect(invalidations).toBe(1)
 
     watcherHarness.closeErrors = 1
     watcherHarness.startupErrors.push(new Error('runtime rewatch failed'))
     first.emitter.emit('error', new Error('runtime watch failed'))
-    await settle()
-    await settle()
-    expect(watcherHarness.watchers.length).toBeGreaterThanOrEqual(2)
+    await vi.waitFor(() => { expect(watcherHarness.watchers.length).toBeGreaterThanOrEqual(2) })
     expect(invalidations).toBeGreaterThanOrEqual(2)
     expect(await ctx.skills.snapshot()).toMatchObject({
       skills: [{ name: 'watched-skill' }],
@@ -230,7 +249,7 @@ describe('skill-local watcher failures', () => {
     })
 
     await fiber.dispose()
-    first.emitter.emit('change', join(root, 'watched-skill/SKILL.md'))
+    first.emitter.emit('change', join(first.path, 'watched-skill/SKILL.md'))
     first.emitter.emit('error', new Error('late error'))
     await settle()
   })
@@ -254,9 +273,11 @@ describe('skill-local watcher failures', () => {
     if (original === undefined) throw new Error('expected a root watcher')
 
     await rm(root, { recursive: true })
-    original.emitter.emit('unlinkDir', root)
+    original.emitter.emit('unlinkDir', original.path)
     await vi.waitFor(() => { expect(original.closeCalls).toBeGreaterThan(0) })
-    expect(watcherHarness.watchFiles.some(control => control.path === root)).toBe(true)
+    await vi.waitFor(() => {
+      expect(watcherHarness.watchFiles.some(control => control.path === original.path)).toBe(true)
+    })
 
     await fiber.dispose()
   })
@@ -280,11 +301,11 @@ describe('skill-local watcher failures', () => {
     if (original === undefined) throw new Error('expected a root watcher')
 
     await rm(root, { recursive: true })
-    original.emitter.emit('unlink', join(root, 'old-skill/SKILL.md'))
+    original.emitter.emit('unlink', join(original.path, 'old-skill/SKILL.md'))
     await settle()
     expect(await ctx.skills.snapshot()).toEqual({ skills: [], complete: true })
 
-    const missingRoot = watcherHarness.watchFiles.find(control => control.path === root)
+    const missingRoot = watcherHarness.watchFiles.find(control => control.path === original.path)
     expect(missingRoot).toBeDefined()
     await writeSkill(root, 'recreated-skill')
     missingRoot!.listener({} as Stats, {} as Stats)

packages/subagent/subagent/tests/list-children.spec.ts

@@ -1055,7 +1055,7 @@ describe('SubagentService.listDescendants', () => {
   })
 
 
-  it('walks a deeply nested ordinary-session chain without consuming the call stack', async () => {
+  it('walks a deeply nested ordinary-session chain without consuming the call stack', { timeout: 20_000 }, async () => {
     const { ctx, parent } = await setup([])
     const depth = 10_000
     let parentId = parent.id