[Bug][Windows] atomic-write writer lock leaks after first write, breaking all settings persistence (dsh web)

[MAPLEYOU]

Summary

On Windows, @deepseek-ai/dsh-atomic-write leaks the writer lock file after the first successful write. Every subsequent withFileLock call on the same target then fails with atomic-write: timed out waiting for the writer lock, which breaks all settings persistence in dsh web (onboarding acknowledgement, model settings, API keys, etc.).

Environment

• OS: Windows 11 (also reproduced on Windows 10)
• dsh: @deepseek-ai/dsh@0.1.1-rc.2 (npm dist, dsh web)
• Node: v22.x
• Affected package: @deepseek-ai/dsh-atomic-write 0.1.1-rc.2 (packages/util/atomic-write in this repo)

Symptom

Fresh install, run dsh web, open the Web UI at http://127.0.0.1:3080:

1. Click "Continue" on the welcome/beta-acknowledgement notice → the write actually succeeds (~/.dsh/settings.yaml now contains ui-onboarding.welcomeNoticeVersion), but ~/.dsh/settings.yaml.lock is left on disk containing the dsh PID.
2. Every following settings write fails. Reproduced directly against the backend:

curl -X POST http://127.0.0.1:3080/api/settings.mutate -H 'content-type: application/json' \
  -d '{"type":"client-request","rpcId":"...","method":"settings.mutate","payload":{"ns":"ui-onboarding","ops":[{"op":"set","path":["welcomeNoticeVersion"],"value":"2026-08-13.1"}]}}'

returns:

atomic-write: timed out waiting for the writer lock at C:\Users\<user>\.dsh\settings.yaml.lock

and the Web UI shows "The acknowledgement could not be saved. Please try again."

So on Windows: first write works, all later writes fail until the leftover .lock file is deleted manually.

Root cause

packages/util/atomic-write/src/index.ts, withFileLock():

try {
  return await operation()
} finally {
  await rm(lockPath, { force: true })
}

The lock release is a single fire-and-forget rm. On Windows, right after writeFileAtomic writes the target, antivirus software and/or file watchers (chokidar is watching these files in dsh) transiently hold an open handle to the freshly written .lock file. The rm then fails with EACCES/EPERM/EBUSY, the rejection is unhandled, and the lock file stays on disk forever.

Since withFileLock refuses to remove a lock it does not own (correctly), every later writer waits DEFAULT_LOCK_WAIT_MS (2 s) and fails. The design intentionally keeps lock-file age-based recovery out of band, so the leaked lock never heals by itself.

This is much easier to hit on Windows than on Linux/macOS due to mandatory file sharing semantics, which likely explains why it survived CI.

Fix

Branch on my fork: https://github.com/MAPLEYOU/deepseek-harness/tree/fix/atomic-write-lock-release-retry

Make the release path resilient instead of fire-and-forget:

• retry the async rm a bounded number of times with exponential backoff (25 ms → 250 ms);
• fall back to synchronous rmSync retries when the async path keeps failing;
• if the lock still cannot be released, emit process.emitWarning(..., { code: 'ATOMIC_WRITE_LOCK_LEAKED' }) instead of an unhandled rejection — the data write already succeeded, so the caller should not see an error, but the leak becomes observable.

The acquisition path (wx create + contention backoff) is untouched; orphan-lock ownership semantics are unchanged.

Tests added in packages/util/atomic-write/tests/atomic-write.spec.ts covering:

• transient EPERM on lock release → lock still removed, operation result preserved;
• permanent release failure → warning with ATOMIC_WRITE_LOCK_LEAKED, write still succeeds;
• release failure combined with an operation error → operation error propagates, warning still emitted.

Full suite (12 tests) passes locally on Windows.

Happy to open a PR if welcome — I saw CONTRIBUTING.md says external PRs are not accepted at this stage, so posting here instead. If the team prefers a different channel or wants a patch file instead, let me know.

Workaround for affected users

Delete the stale lock file and restart dsh:

del "%USERPROFILE%\.dsh\settings.yaml.lock"

[weijiafu14]

定位很干净（finally 里那句 fire-and-forget 的 rm 在 Windows 上被杀软/文件监视器持有的句柄挡下、rejection 无人处理、锁文件永久留下）。补一件：修复不该只是"重试那个 rm"，因为按你的描述，这个锁连重启都自愈不了——而自愈所需要的信息其实已经写在锁文件里了。

锁文件里有 PID，而没人读它

你原文写的：

~/.dsh/settings.yaml.lock is left on disk containing the dsh PID
…
由于 withFileLock 拒绝移除一把不属于自己的锁（这是对的），后续每个写者都要等满 DEFAULT_LOCK_WAIT_MS

这两句合起来就意味着：进程重启之后，那把锁里记的是一个已经不存在的 PID，而新进程仍然认为"这不是我的锁，我不能动" ——于是需要人工删文件。你正是这么描述的（"until the leftover .lock file is deleted manually"）。

所以除了重试释放之外，还有一条更根本的补法：

拿锁之前先看锁里那个 PID 还活着没有。不活着 ⇒ 这是一把孤儿锁，可以接管。

它的好处是同时治两种情况：

情况	只加"重试 rm"	加上"陈旧 PID 可接管"
释放时 rm 暂时失败，但进程还活着	✅ 重试能救	✅
进程崩溃 / 被 kill / 断电，锁留在盘上	❌ 永久卡住	✅ 下次启动自动接管
你报的这一例（rm 失败 + 后续都失败）	✅	✅

第二行是重试方案完全覆盖不到的，而它在 Windows 上并不罕见（任务管理器结束进程、蓝屏、Windows 更新重启）。

（"拒绝移除不属于自己的锁"这条设计是对的，它防的是并发写者互相踩；但它防不了、也不该防"持有者已经不存在了"。判据是PID 是否存活，不是"是不是我的"。这是文件锁的标准做法。）

实现上的注意：Windows 上 PID 会被复用，所以严格做法是在锁里除了 PID 再写一个启动时间戳或随机 token，接管前两者都对不上才判定为孤儿。这一点值得在提案里点一句，否则容易被评审以"PID 复用不安全"驳回。

顺带：这个 bug 的影响面可能比标题写的还大

你说它"breaks all settings persistence"，并举了 onboarding、模型设置、API key。补两条这个社区里同样表现为"设置存不下来"的报告，帮你把它和它们区分开——否则用户很容易把三件事混成一件：

• #2239：客户端 SettingsScopeController.write() 捕获 settings-not-exposed 后只重读、不暴露任何错误，界面表现为"点了没反应"；
• #4695：非 loopback 访问时 Settings 面板整个是 unavailable scope，报"settings are unavailable in this browser"。

这三者的区分判据很清楚，值得写进你的帖子帮后来人自查：

• 你这条：写请求发出去了、后端明确返回 atomic-write: timed out waiting for the writer lock；盘上有一个 .lock 残留；
• Plugin settings namespaces cannot be exposed to the settings UI | 插件注册的 settings namespace 无法暴露给设置界面 #2239：写请求发出去了、被拒、但客户端把错误吞了——界面完全没反应；
• [Bug] 非 loopback 访问时 Settings 面板报错 "settings are unavailable in this browser" #4695：根本没发出 Settings RPC——因为浏览器 scope 从初始化起就是 unavailable。

（DevTools 的 Network 面板一眼能分：有没有请求、有没有响应、响应说了什么。）

你这条难得地属于报错说人话的那一类（错误信息直接点名了锁文件的完整路径），这在这个社区里不多见——建议在帖子里把那句原始报错保留在显眼处，它是用户能自助的关键。

一个立刻能用的自救（给搜到这帖的人）

删除 %USERPROFILE%\.dsh\settings.yaml.lock

（确认 dsh 没在运行，或者确认文件里那个 PID 不是当前 dsh 的。）

边界与利益相关

我们不修 DSH 自家组件——@deepseek-ai/dsh-atomic-write 在 DSH 里。上面全是设计建议与跨帖区分；我没有 Windows 环境、没有复现过这条，根因完全采信你的分析，#2239 / #4695 也都是别人的报告。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销——这是 DSH 的原子写工具包在 Windows 上的行为，装什么插件都不改变它。

[nokkies]

Reproduced and fixed locally. Your root cause is right, and there is a second defect hiding in the same three lines that a retry alone does not address.

The retry, and why the release specifically cannot be best-effort

force: true covers a lock that is already gone. It does not cover Windows refusing to unlink a file another process holds open, which is exactly what an antivirus scanner reading the fresh write, or a watcher on the same path, does routinely. POSIX unlinks a file with open handles happily, which is why this survived CI on every other platform.

What makes it fatal rather than annoying is the interaction you identified: the contender refuses to remove a lock it does not own — correctly, since age cannot distinguish a crashed owner from a paused one — and nothing ages one out. So a sharing violation lasting milliseconds brands the file permanently, and the write that caused it returns success.

A short retry covers the transient case:

const MAX_LOCK_RELEASE_ATTEMPTS = 5
const LOCK_RELEASE_RETRY_MS = 20

with exponential backoff — under 350 ms worst case, against a handle usually held for tens of milliseconds.

The part I would argue for beyond a retry: when the release still cannot happen after a successful operation, that has to be reported rather than swallowed. Swallowing returns success while every future write to the file is already doomed, which is the failure you spent this investigation on. Failing loudly at least names the file to delete:

atomic-write: wrote <target> but could not remove its writer lock at <target>.lock;
every later write to this file will time out until it is deleted

The second bug in those three lines

finally { await rm(...) } does not merely leak — a throw inside finally replaces the operation's own error. So when a settings write fails for its own reasons and the release then refuses, the caller is told about the lock and never about the real cause. That one is platform-independent and silent.

The split that fixes both: strict release on the success path, quiet best-effort release on the failure path so it cannot speak over an error already in hand.

try {
  const result = await operation()
  await releaseFileLock(lockPath, 'strict')
  return result
} catch (error) {
  await releaseFileLock(lockPath, 'best-effort')
  throw error
}

Regression coverage

Four cases, all failing before the change, with the unlink refusal injected rather than waited for. The one worth copying is the reported symptom stated directly: two writes in a row, a transient refusal injected on each release, asserting the second one lands — because that is the user-visible bug, and a test that only checks the first write passes against the broken code.

The other three: the lock is gone after a transient refusal (asserting the lock's absence, not merely that nothing threw — a swallowed failure also does not throw, and bricks the file); a permanent refusal surfaces and names the file; and a stuck release never masks the operation error it is unwinding.

Worth noting for anyone hitting this now: deleting the stray settings.yaml.lock does fully recover it, since the file itself was written correctly every time.

[nokkies]

A branch carrying a fix for this is available, based directly on cd5ef8148 (0.1.2-alpha.1) so it applies with git am -3:

https://github.com/nokkies/dsh-upstream-patches/tree/fix/atomic-write-lock-release

It retries the lock release and never leaks the lock on failure.

This branch carries the source change only, not its tests, and that is deliberate. Our test harness for this package has diverged: we replaced the boolean failLockCreateWithEPERM with epermFailures/rmFailures counters, because the fix turns on telling a transient refusal (Windows refusing a delete-pending name once) from a permanent one. Your harness still uses that flag in six places our diff never touches, so the tests want writing against your shape rather than porting from ours. Shipping them would just conflict.

Offered as-is, no attribution wanted. Take, adapt, or ignore it freely.