Bug: concurrent dsh launches race in healProfilesModuleFallback — TOCTOU ENOENT crashes in ensureSymlink (0.1.1-rc.2, still present on master)

[BiBoyang]

Summary

When several dsh processes start concurrently while the profile module fallback needs healing (e.g. first launch after switching dsh versions), some processes crash with ENOENT inside ensureSymlink. The lstatSync → readlinkSync → unlinkSync sequence has no concurrency guard; only the final symlinkSync call tolerates losing the race (EEXIST branch).

Environment

• @deepseek-ai/dsh 0.1.1-rc.2 (npm latest as of 2026-08-24)
• macOS, Node.js v25.4.0
• $DSH_HOME = ~/.dsh (default), profile headless

Observed

Three dsh --profile headless --patch <overlay> <prompt> processes launched concurrently right after switching from 0.1.0-rc.6 to 0.1.1-rc.2 (so every link in ~/.dsh/profiles/node_modules/ still pointed at the old install and needed re-pointing). Two of three crashed within ~270 ms, exit code 1:

Error: ENOENT: no such file or directory, readlink '/Users/.../.dsh/profiles/node_modules/commander'
    at readlinkSync (node:fs:1761:18)
    at ensureSymlink (.../@deepseek-ai/dsh-app-boot/lib/index.js:380:7)
    at healProfilesModuleFallback (.../dsh-app-boot/lib/index.js:436:3)
    at prepareProfile (.../dsh/lib/profile-boot-*.js:141:2)

Error: ENOENT: no such file or directory, unlink '/Users/.../.dsh/profiles/node_modules/@deepseek-ai/cordis-plugin-timer'
    at unlinkSync (node:fs:1922:11)
    at ensureSymlink (.../@deepseek-ai/dsh-app-boot/lib/index.js:381:3)
    at healProfilesModuleFallback (.../dsh-app-boot/lib/index.js:436:3)

Re-running the same workload afterwards (fallback already healed) is stable — zero crashes across dozens of launches.

Root cause

ensureSymlink (packages/boot/app-boot/src/profile.ts:171, identical on master and in the 0.1.1-rc.2 bundle):

• lstatSync (line 174) is guarded — ENOENT is swallowed.

• readlinkSync (line 184) is unguarded — crash window: the link existed at lstat, another healer unlinked it before our readlink.

• unlinkSync (line 187) is unguarded — crash window: another healer already unlinked the wrong-target link.

• symlinkSync (line 190) is guarded (EEXIST + verify), and its comment (lines 192–194) shows concurrent healing was anticipated:

  Concurrent launches heal the same fallback; losing the race to a process writing the identical link is success, anything else is not.

The guard covers only the create step; the read and delete steps before it are missing the same "losing the race is success" semantics.

Why steady state is safe

When links already point at the right targets, readlinkSync(link) === target returns early — no filesystem mutation, no race window. The bug only fires when many links need re-pointing AND launches are concurrent: version switch, first install, or a moved npx cache. That is why single-process usage never hits it.

Independent reproduction

A controlled experiment with a synthetic $DSH_HOME pre-seeded with 120 wrong-target links: a single process healed all 120 without error; 16 concurrent processes reproduced 4 crashes (3× readlink ENOENT, 1× unlink ENOENT) on the first round.

Suggested fix

Give readlinkSync/unlinkSync the same race-tolerant semantics as the EEXIST branch: catch ENOENT, re-check readlinkSync(link) === target, treat a match as "another process already healed this link" and return. A lockfile around healProfilesModuleFallback would also work but is heavier.

Context

Found by a regression-eval harness (dsh-eval-harness) that runs concurrent headless dsh sessions and captures per-attempt stderr; the crash surface appeared exactly on the first run after the eval pinned dsh 0.1.0-rc.6 → 0.1.1-rc.2.

[Jstn-1g]

I reproduced this and published a discussion-first reference implementation:

• commit 032150f
• reference branch

The change replaces one-shot fallback healing with a bounded per-link convergence loop for transient inspect, read, unlink, and create races. It accepts a same-target winner, while persistent real entries, an already-observed different target, and non-race filesystem failures still fail loud. Because Node exposes no compare-and-unlink primitive, the competing-target protection is explicitly best-effort over observed states rather than a cross-process lock.

Verification on Windows:

• reporter-shaped readlink/unlink race regressions pass; 41 focused tests total
• all 133 app-boot tests pass
• profile.ts has 100% statement/branch/function/line coverage (164/164, 88/88, 24/24, 144/144)
• four repeated real-process stress rounds at 24 concurrent processes × 240 stale links completed with zero failures
• full typecheck, lint, documentation checks, and EN/ZH pairing pass

No upstream PR was opened; this is a reviewable reference for the project’s Discussion-first workflow.

[BiBoyang]

Nice work — the convergence loop covers exactly the two crash sites we hit (readlink :380, unlink :381).

Our original crash was macOS and your stress run was Windows, so I ran the macOS side (Node v25.4.0, your reference/discussion-4312-concurrent-heal branch):

• app-boot suite: 133/133 pass, incl. the 41 race regressions in profile.spec.ts
• A/B stress on the real 0.1.1-rc.2 dependency closure, 432 wrong-target links re-pointed per round:
  • shipped 0.1.1-rc.2: 23/48 crashed (16 concurrent × 3 rounds), both ENOENT shapes at :380/:381, byte-identical to the original incident
  • your fix: 0/48, plus 0/96 at 24 concurrent × 4 rounds

Holds on the POSIX side. Loop closed.