[Bug] 残留的空 .credentials.yaml.lock 让 web 宿主每次启动都失败：启动读取会话密钥也要拿写锁，而非原子创建留下的空锁不在 master 孤儿锁接管范围内（0.1.7-rc.1 实测，master 477b4f4 核对）

[TT-Wang]

同一问题也记录在 https://github.com/dsh-external/issues/issues/648 。按 CONTRIBUTING 在这里报告，并与 #7158 / #7696 / #7634 关联。

现象

一台机器上常驻的 dsh --profile web 服务（launchd KeepAlive）从 2026-09-12 起每次启动都失败，被 launchd 反复拉起，两周里重启了 26252 次，日志涨到 58 MB。每次的报错都一样：

dsh: plugin tree failed to load: failed to apply loader entry connection (@deepseek-ai/dsh-client-connection):
atomic-write: timed out waiting for the writer lock at ~/.dsh/.credentials.yaml.lock

现场的锁文件是空的（0 字节，没有 PID），创建时间 2026-09-12 22:20:32；.credentials.yaml 本身从 08-31 起没被改过。也就是说，某个进程独占创建了锁、还没写进 PID 就退出了，这把锁此后再没人能拿到，也没人能回收。手动删掉锁文件后恢复。

复现（0.1.7-rc.1 实测）

export DSH_HOME="$(mktemp -d)"
dsh --profile web --port 5391 --no-open        # 首次启动：生成 client-connection/browser-session 记录，看到启动 URL 后停止
: > "$DSH_HOME/.credentials.yaml.lock"         # 等价于：持锁进程在 wx 创建之后、写入 PID 之前退出
dsh --profile web --port 5392 --no-open        # 约 33 秒后退出，退出码 1

dsh: startup failed: 1 required plugin did not activate

Failed plugins (1):
  connection (required)
    Package: @deepseek-ai/dsh-client-connection
    Error: atomic-write: timed out waiting for the writer lock at <DSH_HOME>/.credentials.yaml.lock
        at withFileLock (.../packages/util/atomic-write/lib/index.js:141:37)

原因（三处叠加，均已在 master 477b4f4 上核对）

1. 每次启动都要拿凭据文件的写锁，哪怕只是读。 BrowserAuth.create → initializeSecret（packages/client/connection/src/browser-auth.ts）每次都调 credentials.modifyRecord(AUTH_RECORD_KEY, …)。记录已存在时回调返回 undefined、什么也不写，但 credentials-local 的 modifyRecord 无条件先进 withFileLock(this.spec.filename, …, { waitMs: DOCUMENT_LOCK_WAIT_MS })（30 秒）。所以一把残留的凭据锁 = connection 这个 required 插件激活失败 = 整个 web 宿主起不来，而且每次重启都一样。
2. 锁的创建不是原子的，会留下"没写完"的锁。 withFileLock 用 writeFile(lockPath, `${process.pid}\n`, { flag: 'wx' }) 创建锁：这是"独占创建 + 写入"两步。进程在两步之间退出，就留下空锁；另外，如果写入本身失败（例如 ENOSPC/EIO），isLockContention 判为非争用、直接抛出，已经创建的空锁文件也不会被删除。
3. master 新加的孤儿锁接管恰好不覆盖这种锁。 master 的 takeOverExitedLock / holderExited 只在内容严格匹配 ^\d+\n$ 且 PID 探测为 ESRCH 时接管；注释写明"其他内容是正在写入或被截断，证明不了持有者的任何情况"，于是空锁永远被当作"有人持有"来等待，直到超时。也就是说，第 2 点产生的锁，正是第 3 点不会回收的锁；在 master 上，上面的复现依然会失败（按代码推断：holderExited('') 返回 false，withFileLock 等满 30 秒后抛出）。

建议的修法（结构性的，而不是在报错处加补丁）

• 让锁"要么不存在，要么内容完整"：把 <pid>\n 先写进一个唯一的临时文件，再用 link(temp, lockPath) 原子地发布（EEXIST 即争用），最后删除临时文件。这样"残缺的锁"这个状态不再可能出现，master 已有的 ESRCH 接管就能覆盖所有崩溃情形，写入失败也不会留下空锁。
• 读不需要写锁：initializeSecret 先读已有记录（无锁），只有记录不存在时才走 modifyRecord 创建（回调里已有对 current 的复核，天然是 double-check）。稳态启动就不再依赖写锁，一把残留锁最多影响"首次创建密钥"的那一次启动。

相关讨论：#7158（超时报错应给出持锁 PID 和处理办法）、#7696（孤儿锁读 PID 回收，master 已实现）、#7634（孤儿 profile 锁导致 settings 迁移静默丢失）。本 issue 的新情况是：空锁（这两处提议和 master 的实现都处理不了）以及凭据锁让 web 宿主整体无法启动。

环境

• 现场：macOS，dsh 0.1.2-rc.1 源码（a66e470）以 launchd KeepAlive 常驻，DSH_HOME=~/.dsh
• 复现：0.1.7-rc.1（46a7f68），macOS，Node v22.22.3
• 代码核对：master 477b4f4（2026-09-24）

[KongFUN2018]

补一条 Windows 上的实测触发路径，正好落在你第 2 点举的 ENOSPC/EIO 那一类，但错误码是 EMFILE —— 而且它不需要进程崩溃就能造出空锁。

现场

Windows 11，dsh web 冷启动。启动时并发 import 150+ 插件条目，进程文件句柄峰值恒定卡在 8459（= 8192 + 267 基线，疑似硬顶）。connection 的 initializeSecret 恰好在这个窗口里抢 .credentials.yaml 的写锁：

• open(lockPath, 'wx') 成功（还有句柄余量）
• 紧接着的 write 撞上 EMFILE
• isLockContention(EMFILE) → false → 直接抛出，已创建的空锁文件留在盘上
• 之后每次启动都改报 timed out waiting for the writer lock —— 正是你说的第 3 点：holderExited('') 返回 false，空锁永远被当"有人持有"

也就是说：第一次受伤是 EMFILE，第二次及以后看到的是锁超时。报错信息指向的是第二次受伤，排查时容易顺着"锁残留"往下查，而漏掉"为什么会残留"。

概率性复现：观测到 4 次挂 2 次。另外用裸 Node 打开同一路径 3 毫秒成功，可直接证伪"路径/权限有问题"这条线。

本地补丁（三处，跨 0.1.5-rc.1 → 0.1.6-alpha.2 → 0.1.7-rc.2 三个版本、16 天，每次升级重打）

// 1. isLockContention：EMFILE 是启动风暴下的暂时性争用，不是永久失败
if (code === "EMFILE") return true;

// 2. 熬过启动风暴
const DEFAULT_LOCK_WAIT_MS = 6e4;            // 上游是 2e3

// 3. withFileLock：catch 里打 partial 标志，循环内清掉自己的半成品锁
//    （open 成功、write 失败会留下空锁；不清掉，下一次 open(wx) 会死等自己的残留）
} catch (error) {
    if (error?.code === "EMFILE") partial = true;
    if (!await isLockContention(error, lockPath)) { ... }
}
if (partial) {
    await rm(lockPath, { force: true });
    partial = false;
}

补丁叠在 0.1.6/0.1.7 新增的 EPERM 重试分支之上（保留上游逻辑，不覆盖）。代价是启动变慢：URL 出现在 21-30 秒，正常约 10 秒。

两点补充

1. 触发错误码不止 ENOSPC/EIO：Windows 上更常见的是 EMFILE，而它是可重试的（和你举的两个不同），把它丢进退避循环比抛出去更合适。你提议的 link 原子发布能一并解决这两类；本地补丁第 3 处只是把"残缺锁"的生存期缩到一个重试周期内。

2. 上游两个版本都没修：0.1.6-alpha.2 与 0.1.7-rc.2 的 DEFAULT_LOCK_WAIT_MS 仍是 2e3，isLockContention 仍只认 EEXIST/EPERM（新增的 EPERM 分支只处理"未确认的权限错误"，不覆盖写入失败）。我看到的关联讨论里，@deepseek-ai/dsh-atomic-write profile写锁残留导致dsh plugin卡满120秒后失败 #7696 零回复，[Bug][Windows] atomic-write writer lock leaks after first write, breaking all settings persistence (dsh web) #4689 有第三方修复分支但没有官方回应，Writer-lock timeout error names only the path, leaving an orphan lock unrecoverable in practice #7158 / Orphaned profile writer lock silently drops the legacy settings.yaml migration (settings lost, welcome notice cannot be acknowledged) #7634 我也没看到官方的处理意见。

[Max6617]

Another data point: still reproducible on Desktop 0.2.0-rc.2 (nightly, Windows 11 26300, Electron 44 / Node 24.18.1). It hit me on two consecutive days.

How the empty lock appeared in my case: it's the same EMFILE path @KongFUN2018 described, but the trigger wasn't plugin imports. It was dsh-storage-json loading all 14,136 files of ~/.dsh/storages/session_projcache/sessions/ with one unbounded Promise.all (separate report: #9609). Handles ran out about 2.6 s into startup. connection → withFileLock created .credentials.yaml.lock with wx, the PID write then failed with EMFILE, and a 0-byte lock was left behind:

.credentials.yaml.lock   0 bytes   created 12:49:42   (exactly when that EMFILE run happened)

Every later start then failed the same way:

connection (required)
  Package: @deepseek-ai/dsh-client-connection
  Error: atomic-write: timed out waiting for the writer lock at C:\Users\<user>\.dsh\.credentials.yaml.lock

In the Desktop app this either leaves the main window hidden (separate report: #9610) or shows "DeepSeek Harness is unavailable" after ~64 s. I had already renamed the same 0-byte lock away the day before, and it came back.

I'd add one point to the fixes already proposed in this thread: withFileLock should remove its own partially written lock when the PID write fails (it created the file, so it knows it owns it). That alone would have prevented both of my incidents. Publishing via temp file + link(), as the original post suggests, would avoid empty locks altogether.