[Bug: Windows] Settings save intermittently fails with EPERM — rename in writeFileAtomic needs a transient-failure retry

[xiaoyuyu6420]

Summary

On Windows, saving settings in the Web UI (e.g. the model API key) intermittently fails with:

EPERM: operation not permitted, rename 'C:\Users\...\.dsh\settings.yaml.<hex>.tmp' -> 'C:\Users\...\.dsh\settings.yaml'

Root cause

writeFileAtomic in @deepseek-ai/dsh-atomic-write commits by writing a random-suffix .tmp sibling and renaming it over the target in a single step — with no retry. On Windows, antivirus real-time scanners and search indexers briefly open an exclusive handle on the freshly created .tmp file (or the target), and a Windows rename over a file with an open handle fails with EPERM. The failure is purely transient, but it propagates straight to the UI.

Upstream libraries (write-file-atomic, graceful-fs) handle this exact case with bounded retries.

Reproduction

Looping the same write-temp-then-rename sequence 60 times against ~/.dsh on Windows 11 (stock Defender, no exotic software) failed 1 of 60 times (~1.7%) — every retry immediately after a failure succeeds. This matches the "saving settings sometimes errors, saving again works" symptom.

Fix

I've pushed a minimal fix to a fork branch: xiaoyuyu6420/deepseek-harness@master...xiaoyuyu6420:deepseek-harness:fix/atomic-write-windows-rename-retry

writeFileAtomic now routes the rename through a renameWithRetry helper: EPERM/EBUSY are retried with bounded backoff (3 attempts, 50→200 ms); every other failure — or one that survives the retries — is rethrown unchanged, so callers keep observing the original error. Unit tests cover the transient-retry-then-commit path, the exhausted-retry rethrow, an immediate EACCES rethrow without retrying, and an error without an errno code.

After the fix, the same stress loop completes 300/300 writes successfully.

Since CONTRIBUTING.md explains external pull requests are not accepted at the moment, I'm following the contributing guide and posting here instead — the branch is MIT-licensed like the rest of the repo, so feel free to cherry-pick it wholesale or reimplement the retry in whatever shape fits your conventions. Happy to rework it if a maintainer prefers a different approach (e.g. a shared retry helper or fsync-related changes from the existing TODO).

Environment

• Windows 11 (10.0.26200), Node v24.13.0
• Built from source at master 47f9438
• Symptom first observed with the published @deepseek-ai/dsh@0.1.0-rc.6 via npx @deepseek-ai/dsh web

[xiaoyuyu6420]

感谢分享实测经验！对照你们的做法，逐条说明一下当前修复（fix/atomic-write-windows-rename-retry 分支，writeFileAtomic 内的 renameWithRetry）的取舍：

1. 错误分类先于重试 — 已采用同样思路：重试白名单只含 EPERM/EBUSY 两个瞬态码，ENOSPC、ENOENT 等其他错误码第一次失败即抛出原始错误，调用方拿到的语义就是"这个错误不会自己消失"。

2. 有界重试 + 指数退避 — 3 次重试、50ms→100ms→200ms 指数退避（上限 200ms）。相比你们 100ms 起步，这里第一次重试更早，但三次总等待窗口约 350ms，足以覆盖常见的 AV/索引扫描窗口；未加抖动，因为同一文件的重试循环不存在多进程同步退避的共振场景。

3. fallback 副本路径 — 没有做：writeFileAtomic 的失败语义是"目标文件保持旧内容"（temp 全量写成功后才 rename，任何失败都清理 temp 并抛出原始错误），不存在"以为保存了、其实丢了"的静默窗口；写副本反而会引入第二份需要清理的状态。

4. verify 读回 — 这个包明确将 crash durability（fsync）排除在 scope 外（源码里有对应 TODO 注释）；verify 防的"rename 成功但未落盘"属于掉电/缓存范畴，与 fsync 是同一个取舍决定。

5. 重试计数可观测 — 有价值的点。这个包是 zero-dependency 底层 util，不便引入 logger；更合适的观测点是上层保存路径。后续可以考虑把重试次数透出给调用方（比如挂在错误对象上），先记下这条。

[xiaoyuyu6420]

第 5 点采纳了，已实现并推到 fix/atomic-write-windows-rename-retry 分支（提交 bb7ee360）：

• 成功路径：writeFileAtomic 返回值从 void 改为 { attempts }，每项 { attempt, retried?, delay? }。retried/delay 只出现在被重试的尝试上，成功项是裸 { attempt: N }——"持续占用"信号就是 result.attempts.length > 1，不需要等到出错，和你们说的"成功路径的重试统计比错误路径更早暴露问题"完全一致。
• 失败路径：重试耗尽或非瞬态码抛出时，同一个数组挂在 err.attempts 上；最终失败的 code 由 err.code 本身携带，不在数组里重复（终止项与成功项同形，靠错误对象本身区分）。
• 上层消费：if (result.attempts.length > 1) log.warn(...)——util 保持零依赖零日志，可观测性决策完全留给调用方。

测试补了四个断言形状：单次成功、重试两次后成功（[{1, EPERM, 50}, {2, EPERM, 100}, {3}]）、重试耗尽、非瞬态码首试即抛（[{1}]）。

"没有这个字段，重试是隐形的"这个总结很准——之前那 1.7% 的偶发 EPERM 就是典型的"重试了但没人知道"。感谢补充这点。

[xiaoyuyu6420]

补一个 diff 直达链接，方便团队直接取用参考实现（注意到仓库暂不接受外部 PR，分支在 fork 上）：

Compare/diff: main...xiaoyuyu6420:fix/atomic-write-windows-rename-retry

单个 patch 下载：给上面的 URL 加 后缀即可。共 3 个提交：重试修复（3c1c36ca）、重试/非重试路径测试（027993b3）、attempts 历史（bb7ee360）。本地 pnpm run typecheck 与 atomic-write 全部测试（9/9）通过。