Windows: editing an existing config file fails with "ReplaceFileW EACCES (Win32 5)" when the target is watched by HMR

[Wayne036]

Summary

On Windows, the edit tool (and write over an existing file) fails with ReplaceFileW EACCES (Win32 5) whenever the target file is being watched by the harness's own HMR (cordis-plugin-hmr → chokidar fs.watch on profile config files). Writing new files works fine; replacing existing, watched files fails consistently. The identical replacement via rename (MoveFileExW) succeeds under the same conditions — the failure is specific to ReplaceFileW semantics on a file that has an open watcher handle.

Environment

• dsh 0.1.0-rc.7 (@deepseek-ai/dsh, @deepseek-ai/dsh-fs-local)
• Windows (10/11), Node 22 / 24
• Repro target: C:\Users\Administrator\.dsh\profiles\web\cordis.patch.yml (watched by HMR)

Repro steps

1. Start dsh web.
2. In a session, ask the agent to edit ~/.dsh/profiles/web/cordis.patch.yml (existing, HMR-watched file).
3. Observe the tool error:
   Error: ReplaceFileW EACCES (Win32 5): C:\Users\Administrator\.dsh\profiles\web\cordis.patch.yml
4. The file is not read-only and the ACL grants FullControl (verified via attrib / icacls).
5. Writing a brand-new file in the same directory succeeds.

Root cause

dsh-fs-local's writeFileAtomic publishes on win32 via ReplaceFileW (kernel32). When the destination has an open watcher handle (chokidar/fs.watch used by cordis-plugin-hmr on profile config files), ReplaceFileW returns ERROR_ACCESS_DENIED (5), while MoveFileExW(MOVEFILE_REPLACE_EXISTING) succeeds.

Verified by calling the Windows API directly with the same FFI (koffi) that dsh-fs-local uses:

Target state	ReplaceFileW	rename (MoveFileExW)
fs.watch handle open on target	❌ fails (Win32 5)	✅ succeeds
no watch handle	✅ succeeds	✅ succeeds

Suggested fix

In dsh-fs-local/lib/index.js writeFileAtomic, the win32 branch already falls back to rename() when ReplaceFileW fails with ENOENT; extend the fallback to also cover EACCES (the watched-target case):

} catch (error) {
    if (!isENOENT(error) && !isEACCES(error)) throw error;
    await rename(tempPath, absolutePath);
}

A genuinely locked/denied target also fails the rename fallback, so this cannot mask a real access problem. Note the copyFileDacl step before ReplaceFileW already copies the target ACL onto the staging file, so the rename path retains the ACL intent.

Related observation

A child process running dsh --profile web (profile-boot prepareProfile → writeFileSync(cordis.yml)) can also hit EPERM ... open ...cordis.yml when the parent holds a watch handle on the profile root file — same underlying watcher-handle conflict.

Workaround (until fixed)

Edit watched config files via a new patch/overlay file (new files are unaffected), or via pwsh Set-Content, or fall back to rename.

[zoahdev]

核验通过（对照 main/master HEAD 99f6f02 rc.7 TS 源码）——根因与修复建议都成立，且你的"watch handle 与 ReplaceFileW 冲突"判断与代码路径一致。

1. 代码确认。 packages/fs/fs-local/src/fsio.ts:582-594：win32 + mode 分支 await replaceFile(absolutePath, tempPath)（win32.ts:124-137 的 replaceFileWin32，ReplaceFileW），catch 里 只对 isENOENT 回退 rename，其余错误直接抛——被 watch 的既有文件命中 ERROR_ACCESS_DENIED(5) 时即 EACCES，直接失败。:50 已有 isEACCES/EPERM helper，说明这个语义在包内是现成的。

2. 修复正确：把回退条件扩展为 if (!isENOENT(error) && !isEACCES(error)) throw error——你已验证 rename(MoveFileExW) 在 watch handle 打开时成功；真被锁/拒权时 rename 同样失败，不会被掩盖。copyFileDaclWin32 在 ReplaceFileW 前已把 ACL 拷到 staging 文件（win32.ts:105-122），rename 路径保留 ACL 意图的说法成立。

3. 建议补两件事：

• 回归测试：fsio.spec.ts 用 internals.replaceFile 注入"先抛 EACCES 再成功"（现有测试文件已有 internals 注入模式，fsio.spec.ts:653-771），断言 EACCES 后走 rename 成功、非 EACCES 仍抛；
• 相关观察也值得单独修：prepareProfile 的 writeFileSync(cordis.yml) 撞父进程 watch handle 的 EPERM（你提到的相关观察），与这次是同一"watcher 打开句柄 vs 替换写入"冲突族，建议同一 PR 里把 profile-boot 的写路径也改为原子替换或临时文件 + rename。

需要的话我可以把这个 1 行修复 + 回归测试做成 cherry-pick 分支（按之前的惯例）。

[zoahdev]

cherry-pick 分支已建好（含回归测试）：

https://github.com/zoahdev/deepseek-harness/tree/fix/atomic-write-eacces-fallback

• 基于 main HEAD 99f6f02；改动 = fsio.ts:594 回退条件扩展为 !isENOENT(error) && !isPermissionError(error)（EACCES/EPERM 覆盖，比报告的 EACCES 更全——EPERM 对应你提到的 prepareProfile 场景）；
• 测试：原"EACCES 拒绝"用例改为"EACCES → rename 回退成功"（fsio.spec），另加"非 ENOENT/非权限错误仍 surface + 清理 staging"保持 fail-closed 契约；两个用例定向验证通过（本机其余 8 个 symlink 测试失败为 Windows 未开开发者模式的预存环境问题，与补丁无关）；pre-push 全量 typecheck 过；
• 已登记 zoahdev upstream patch queue（dsh-docs The workspace does not support Chinese path names #47）。

PR 通道开放时可直接 cherry-pick；若你想按自己仓库流程提交也随意使用。

[denial123789]

I published an operator-focused recovery runbook for this failure, pinned to upstream 99f6f02:

https://sandbaseai.github.io/deepseek-harness-handbook/windows-replacefile-eacces.html

One source-detail correction for anyone implementing the proposed upstream patch: the helper at that revision is named isPermissionError and covers both EACCES and EPERM; the currently shipped writeFileAtomic fallback still runs only for ENOENT. The runbook therefore does not present an EACCES-to-rename fallback as released behavior.

For operators who need a safe path before a fix ships, the bounded lifecycle is: stop the exact HMR owner → record attrib and icacls → back up and compare hashes → edit only while stopped → run dsh --profile web --dump-config → restart and smoke-test. A live Set-Content overwrite is intentionally excluded because it can expose partial YAML to HMR, and blanket termination of every node.exe is also avoided.