write: new-file publish uses a hard link, so it fails on exFAT (EISDIR) with no fallback

[phoenix13023]

Labels: bug filesystem windows

Summary

writeFileAtomic publishes a new file with a hard link. exFAT has no hard-link
support, so on any exFAT volume — the common case for removable drives and cross-OS
project shares — the write tool cannot create a single new file. Overwriting an existing
file works, which makes the failure look arbitrary.

Location

packages/fs/fs-local/src/fsio.ts

• :546 staging dir .<name>.<pid>.<uuid>.tmpdir
• :578-583 new-file path: await linkFile(tempPath, absolutePath) → catch → throwGuardedCreateFailure
• :584-594 replace path: ReplaceFileW, with rename fallback → works on exFAT

Measured on this machine (workspace volume = exFAT, harness-home volume = NTFS)

operation	before	after proposed fix
write create new file (on the exFAT volume)	❌ EISDIR	✅
write overwrite a read file (on the exFAT volume)	✅	✅
edit existing file (on the exFAT volume)	✅	✅
raw fs.link (on the exFAT volume)	❌ EISDIR: illegal operation on a directory, link '<…>.tmpdir\a.tmp' -> '<target>'	—
raw open(target,'wx') twice (on the exFAT volume)	2nd → EEXIST, first file untouched	—

The errno is itself a hazard: a hard-link-less volume answers link() as EISDIR
("illegal operation on a directory"), which reads like a path/type bug. In
a recorded runaway session the model concluded from it that its own temp filename was malformed and
burned many steps on that theory.

Why the obvious fallback is wrong

Falling back to plain rename breaks the contract of this code path: createIfAbsent
exists to guarantee no-replace, and rename over an existing target silently clobbers
it (measured: target content A → B).

Proposed patch (in use locally, 144 tests + tsc -b clean)

       try {
         await linkFile(tempPath, absolutePath)
       } catch (error: unknown) {
-        await throwGuardedCreateFailure(error, absolutePath, createIfAbsent.displayPath, inspectPublicationTarget)
+        // `link` is the only primitive that publishes staged bytes with no-replace
+        // semantics, but a hard-link-less volume (exFAT) rejects it outright, so a
+        // new file could not be created at all. Claim the name with an exclusive
+        // create, then rename the synced staging file over that own claim: `wx`
+        // still loses to a concurrent creator with EEXIST, so no other writer's
+        // bytes are clobbered. The weakened guarantee is visibility only — a reader
+        // may briefly observe the claimed-but-empty file instead of nothing.
+        if (!isHardLinkUnsupported(error)) {
+          await throwGuardedCreateFailure(error, absolutePath, createIfAbsent.displayPath, inspectPublicationTarget)
+        }
+        try {
+          const claim = await open(absolutePath, 'wx', 0o600)
+          await claim.close()
+        } catch (claimError: unknown) {
+          await throwGuardedCreateFailure(claimError, absolutePath, createIfAbsent.displayPath, inspectPublicationTarget)
+        }
+        try {
+          await rename(tempPath, absolutePath)
+        } catch (publishError: unknown) {
+          // The name is ours alone, having just won it exclusively, so dropping the
+          // empty claim cannot destroy another writer's file.
+          await rm(absolutePath, { force: true }).catch(() => {})
+          throw publishError
+        }
       }

with

function isHardLinkUnsupported(error: unknown): boolean {
  const code = (error as { code?: unknown }).code
  return code === 'EISDIR' || code === 'EPERM' || code === 'ENOTSUP' || code === 'EOPNOTSUPP' || code === 'EINVAL' || code === 'ENOSYS'
}

Semantics preserved: a real collision is still EEXIST → FS_NOT_OBSERVED; a directory
target is still FS_NOT_REGULAR_FILE (the wx claim fails and the existing inspection
classifies it). Only regression vs the link path: a brand-new file may be observed empty
for an instant. EPERM/EACCES-style permission faults keep their old classification
because the failed claim falls back into throwGuardedCreateFailure.

Suggested tests

1. Mock linkFile to throw EISDIR; assert the file is created and contains the content.
2. Same, but the target already exists; assert rejection is FS_NOT_OBSERVED and the
   existing bytes survive.
3. Same, but target is a directory; assert FS_NOT_REGULAR_FILE.
   CI tmpdirs are usually NTFS/ext4, so case 1 needs the mock — the existing suite already
   uses internals.linkFile, so the seam exists.

---

[173787247]

会话 / 历史（「write: new-file publish uses a hard link, so it fails on exFAT (EISDIR) with no fallback」）

会话数据一般在用户目录下的 dsh 数据路径（随版本可能是 ~/.dsh 或文档写明的 data dir）。重装前应先备份整个数据目录再覆盖。

1. 找到旧版本数据目录（含 session / trajectory 文件）
2. 完整退出 dsh
3. 复原到新版本对应目录后启动
4. 大版本跨越可能不兼容——看 Release note 是否有 migration

不要只拷单个 .jsonl 而漏掉索引/侧车文件（有的版本还有 .zstd 等）。

[PerryLink]

Confirmed on master (c291e79): the createIfAbsent path still publishes via hard link with no fallback.

packages/fs/fs-local/src/fsio.ts:616-621

if (createIfAbsent !== undefined) {
  try { await linkFile(tempPath, absolutePath) }
  catch (error) { await throwGuardedCreateFailure(error, absolutePath, ...) }
}

linkFile defaults to node:fs.link (:591), and exFAT answers link() with EISDIR — so new-file creation fails
while the replace path (ReplaceFileW + rename fallback, :622-633) works fine. Your root-cause claim is correct,
including the observation that plain rename is not an acceptable fallback (it silently clobbers an existing target,
breaking the no-replace contract).

Your proposed patch is the right shape and I endorse it: on a hard-link-unsupported error code
(EISDIR/EPERM/ENOTSUP/EOPNOTSUPP/EINVAL/ENOSYS), claim the name with open(absolutePath, 'wx') (a concurrent creator
still loses with EEXIST → FS_NOT_OBSERVED, so no one else's bytes can be clobbered), then rename the staged file over
the claim, and clean the empty claim on publish failure. The only semantic regression — a reader may briefly observe an
empty claimed file — is acceptable and worth stating in the commit message.

Workaround until fixed: keep new-file writes off exFAT volumes (overwrite/edit continue to work), or apply the local
patch. Note the errno itself misleads agents (EISDIR reads like a path bug) — your "runaway session" observation is a
good argument for getting this merged.