Windows: opening a file preview locks its parent directory (and all ancestors) against rename/delete

[wavingleaf]

[Windows] Opening a file preview locks its parent directory (and every ancestor) against rename/delete

Environment

• dsh 0.2.1-rc.2 (portable build), profile web
• Windows 11, Node 24.19.0, NTFS
• Sandbox: workspace-write (ACL confinement active)

Summary

While a file is open in the Web UI file viewer, the folder that contains the file — and every ancestor of that folder — cannot be renamed or deleted from Explorer. Explorer reports "You need administrator permission to delete this folder", but the DACL grants DELETE and the failure is not a permissions problem. Closing the preview restores normal behavior immediately. This is Windows-specific.

Steps to reproduce

1. Use a workspace, e.g. D:\dsh\DSHWorkspace, and create 校准\dirA\新建 文本文档.md inside it.
2. Open that file in the side panel (file viewer) of the Web UI.
3. In Windows Explorer:
   • deleting dirA succeeds;
   • deleting or renaming 校准 fails with the "needs administrator permission" dialog.
4. Close the preview and repeat step 3: 校准 can be renamed/deleted again.

Evidence

While the preview is open, handle64 (Sysinternals) reports two File handles owned by the dsh host process on the parent folder of the opened file:

node.exe  pid: 23136  type: File  7E0: ...\校准\dirA
node.exe  pid: 23136  type: File  B94: ...\校准\dirA

Renaming the parent folder by MoveFileW:

state	MoveFileW(校准 → 校准-T)
preview open	FALSE, GetLastError() = 5 (ERROR_ACCESS_DENIED)
preview closed	TRUE, error 0

The same test on dirA itself (the folder holding the opened file) succeeds in both states. DELETE access checks on 校准 pass in both states, and the ACL is unchanged — the sandbox's Deny Everyone FILE_DELETE_CHILD ACE is present but is not the cause.

Root cause

@deepseek-ai/dsh-fs-local, LocalFileSystem#watch (lib/index.js):

async watch(target, changed, signal) {
  const path = resolve(this.processPath(target));
  const directory = (await this.stat(target, signal))?.type === "directory";
  const root = directory ? path : dirname(path);   // file target -> watch its parent directory
  const watcher = watch(root, { ignoreInitial: true, depth: 0, ... });
  ...
}

The Web file-resource follower (@deepseek-ai/dsh-api-workspace-files → workspaceFiles.changes) calls this with the opened file, so the watcher root becomes the file's parent directory. On Windows the watcher keeps a real directory handle open.

Windows refuses to rename or delete a directory while any object in its subtree has an open handle — even when that handle was opened with FILE_SHARE_DELETE — and returns ERROR_ACCESS_DENIED (5). Explorer renders that as the elevation prompt "You need administrator permission…", because deleting to the Recycle Bin is a whole-tree rename.

Consequence: opening a preview locks the file's parent directory and, transitively, all of its ancestors — including the workspace root.

Related case (same class, different component)

@deepseek-ai/dsh-skill-filesystem watches every skill root with

chokidar.watch(mode.anchor, { persistent: true, ignoreInitial: true, depth: 1, ... })

which keeps handles on each skill directory (e.g. .dsh/skills/<skill>) and, transitively, on .dsh/skills, .dsh and the workspace root. While dsh runs, renaming/deleting a skill directory or its ancestors fails the same way. (Arguably expected for hot reload, but it has the same Windows side effect.)

Suggested fix

• For non-directory targets, use a watcher that does not keep a directory handle open — fs.watchFile (stat polling) is the simplest; the cost is a refresh latency of one poll interval.
• Alternatively, allow configuring usePolling for file followers and for skill roots.
• If neither is acceptable, document the Windows caveat: "on Windows, an open file preview locks its folder and all ancestors".

Workaround (no code change)

Rename/move/delete the ancestor after closing the preview, or delete recursively (Remove-Item -Recurse, rd /s /q) which deletes item by item instead of renaming the whole tree.

[wavingleaf]

Follow-up: the same Windows lock also happens for directory targets, not only for file previews

Additional measurements on the same machine (dsh 0.2.1-rc.2, Windows 11, NTFS).

Directory targets are affected too

Opening a folder in the UI (file tree / directory view) locks that folder the same way:

• the dsh host holds handles on tmp-诊断-20261029 (2) and on its subfolder 校准 (1);
• MoveFileW(tmp-诊断-20261029 → tmp-诊断-20261029-T) returns ERROR_ACCESS_DENIED (5);
• moving 校准 out of the folder makes the rename succeed immediately (0); moving it back restores 5;
• closing the view releases the handles and the rename succeeds.

Root cause is the other branch of the same function

In @deepseek-ai/dsh-fs-local LocalFileSystem#watch:

const directory = (await this.stat(target, signal))?.type === "directory";
const root = directory ? path : dirname(path);
const watcher = watch(root, { ignoreInitial: true, depth: 0, ... });

For a directory target root = path, so the watcher holds a handle on the directory itself (for a file target it holds one on the parent directory). Both cases hit the Windows rule that a directory cannot be renamed or deleted while any object in its subtree has an open handle — ERROR_ACCESS_DENIED (5), which Explorer renders as "you need administrator permission".

So the fix needs to cover both branches: file target (watch of the parent directory) and directory target (watch of the directory itself).

Verified local workaround

Replacing both branches with polling in a local plugin patch:

• files: fs.watchFile with a 1 s interval;
• directories: a 1 s snapshot compare of mtimeMs | size | entry count | sorted entry names (above 2000 entries only mtimeMs/size are compared).

Result with the patch: preview open → zero handles under the affected subtree; the folder and all its ancestors can be renamed/deleted; the UI still refreshes the open preview and the directory listing within ~1 s.