dsh-skill-filesystem: fatal process exit on ELOOP caused by circular junctions in user skill directory

[q1023240585-code]

Summary

dsh (DeepSeek Harness) crashes with a fatal error and the whole process exits when a user skill directory (e.g. ~/.agents/skills) contains circular junctions (directory A points to B while B points back to A). A single corrupted directory should never take down the entire service.

Environment

• dsh version: 0.1.0-rc.6 (package @deepseek-ai/dsh-skill-filesystem)
• OS: Windows 11 (NTFS junction points; same class of problem exists for symlinks on macOS/Linux)
• Trigger: startup scan of ~/.agents/skills by the skill-filesystem provider

Actual behavior

dsh starts, listens on the port, then the Node.js process dies shortly after with:

dsh: fatal load failure: Error: ELOOP: too many symbolic links encountered, stat 'C:\Users\56891\.agents\skills\cli-anything-wps'
    at async Object.stat (node:internal/fs/promises:1038:18)
    at async NodeFsHandler._addToNodeFs (.../chokidar/handler.js:580:27)

The browser then fails to connect to the GUI (failed to fetch).

Root cause

The skill watcher in dsh-skill-filesystem (lib/index.js) creates a chokidar watcher with followSymlinks: this.config.followSymlinks (default true, watchFollowSymlinks config):

const watcher = chokidar.watch(mode.anchor, {
    persistent: true,
    ignoreInitial: true,
    depth: 1,
    followSymlinks: this.config.followSymlinks,
    ...
});

When the watched root contains circular junctions, chokidar follows the cycle and hits ELOOP. The error handler wired before the watcher is ready rejects the readiness promise, and that rejection is rethrown up the stack:

const onError = (error) => {
    if (!ready) {
        readiness.reject(error);   // <-- ELOOP during initial scan
        return;
    }
    this.handleWatcherError(state, error);
};
...
try {
    await readiness.promise;
} catch (error) {
    await this.closeWatcher(handle);
    throw error;                   // <-- propagates -> fatal
}

replaceWatcher also warns but rethrows:

} catch (error) {
    if (!this.closing) {
        state.unhealthy = true;
        this.ctx.logger.warn(`skill-filesystem: failed to watch ${state.root.path}: ${errorMessage(error)}`);
    }
    throw error;                   // <-- fatal
}

So an ELOOP during the initial scan escapes as a fatal load failure instead of being contained per-directory.

Reproduction (Windows):

# create two skill dirs that point at each other
New-Item -ItemType Junction -Path "$HOME\.agents\skills\a" -Target "$HOME\.claude\skills\a"
New-Item -ItemType Junction -Path "$HOME\.claude\skills\a" -Target "$HOME\.agents\skills\a"
# start dsh -> process exits with ELOOP fatal

Expected behavior

A broken/unreadable skill directory (circular junction, permission error, or any per-directory failure) should:

1. be logged as a WARNING (e.g. WARNING: skipping unreadable skill dir ...) and skipped;
2. not abort the skill scan for the remaining roots;
3. never terminate the dsh process.

Suggested fix

• Route pre-ready watcher errors through the same degradation path as handleWatcherError (warn + mark root unhealthy + skip/retry) instead of rejecting the readiness promise and rethrowing.
• Special-case ELOOP/ELOOP-class errors: drop the affected root from the watch set, emit a warning, and optionally re-probe on the next invalidation cycle.
• Consider detecting cycles during discovery (track visited realpaths per root) so the scan can prune cyclic entries before chokidar follows them.
• Optional hardening: make watchFollowSymlinks default to false for user-level roots, or document the risk.

Notes

• This was hit in the wild: a third-party "sync" tool had converted both sides of ~/.agents/skills and ~/.claude/skills into junctions pointing at each other; dsh died on every startup until the cycles were manually removed.
• Same failure mode applies to any circular symlink/junction under a watched skill root.

[zoahdev]

Confirmed at source level and implemented as a cherry-pick-ready branch.

Source audit (master 47f9438)

The report's read is exact: openRootWatcher rejects the readiness promise on any pre-ready watcher error, openStableWatcher/replaceWatcher propagate it, and under installFailLoud an escaping rejection becomes dsh: fatal load failure - one circular junction kills the whole service.

Patch: fix/skill-filesystem-eloop-contained

https://github.com/zoahdev/deepseek-harness/tree/fix/skill-filesystem-eloop-contained

• ELOOP-class errors (code === 'ELOOP', covering Windows junction cycles and symlink cycles on macOS/Linux) now degrade only the affected root: warn, mark unhealthy, close the partial watcher, return a skip instead of rejecting provider load. The scheduled rewatch retries on the next invalidation, so a fixed junction recovers without a restart.
• Non-ELOOP startup errors keep their existing contract (reject the opening; callers surface or degrade), so no other error-handling behavior changes.
• The skill catalog for every other root stays readable; provider load never rejects on ELOOP.

Verification

• tsc -b tsconfig.host.json - clean
• pnpm vitest run packages/skill/skill-filesystem/tests/skill-filesystem-watcher.spec.ts - 11/11, including a new regression test: ELOOP startup error -> load succeeds, catalog readable, retry recovers (complete: true)
• The only failing tests in the skill-filesystem spec on this Windows runner are pre-existing EPERM symlink-permission cases, unrelated to the change

Thanks for the exact reproduction - this is exactly the "one corrupted directory must never take down the process" class of bug. Happy to open the PR once contributions are enabled.