macOS exFAT 卷上 pnpm install 必现失败：install-lefthook 锁的 inode 所有权校验在 exFAT 上永不成立（stale lock 与 ownership changed 交替循环）

[YuanyuanMa03]

注：本帖初始版本有两处事实错误（系统版本、锁校验失败时机的描述），已根据复查结果更正，机制分析以本版本为准。

环境

• macOS 26.5（Darwin 25.5.0，arm64）
• 仓库位于 exFAT 卷（Samsung T7 USB SSD，diskutil 显示 File System Personality: ExFAT）
• master @ 47f943859b，pnpm v11.7.0

现象与原始输出

pnpm install 在 postinstall 阶段退出 1，两种错误交替出现，删锁重跑也无法恢复。

错误一（锁由上一次失败的 install 遗留），pnpm 实际输出（预先放置内容为 999999 <uuid> 的锁文件模拟遗留死锁后捕获）：

. postinstall$ node scripts/install-lefthook.mjs
. postinstall: [install-lefthook] stale Lefthook installer lock "/Volumes/SamsungT7/git/deepseek-harness/.git/dsh-lefthook-install.lock". Confirm no Lefthook installer is running, remove it manually, and retry.
. postinstall: Failed
[ELIFECYCLE] Command failed with exit code 1.

错误二（手动删除锁文件后重跑），pnpm 实际输出：

. postinstall$ node scripts/install-lefthook.mjs
. postinstall: [install-lefthook] Lefthook installer lock ownership changed for /Volumes/SamsungT7/git/deepseek-harness/.git/dsh-lefthook-install.lock; refusing to remove it
. postinstall: Failed
[ELIFECYCLE] Command failed with exit code 1.

直接复现（node scripts/install-lefthook.mjs，输出逐字未改）

复现错误一：先放置一个内容为 999999 <uuid> 的锁文件（模拟上次失败遗留的死 PID 锁），然后运行：

$ printf '999999 00000000-0000-0000-0000-000000000000\n' > .git/dsh-lefthook-install.lock
$ node scripts/install-lefthook.mjs
[install-lefthook] stale Lefthook installer lock "/Volumes/SamsungT7/git/deepseek-harness/.git/dsh-lefthook-install.lock". Confirm no Lefthook installer is running, remove it manually, and retry.
exit=1

复现错误二（无锁的干净状态直接运行）：

$ node scripts/install-lefthook.mjs
[install-lefthook] Lefthook installer lock ownership changed for /Volumes/SamsungT7/git/deepseek-harness/.git/dsh-lefthook-install.lock; refusing to remove it
exit=1

每次失败都会在 .git/ 遗留一个新锁文件，属主 PID 已随进程退出：

$ cat .git/dsh-lefthook-install.lock
94332 bf3d5d01-2959-4c77-9ee0-decbeacad1ae

于是下一次 install 又报 stale——形成循环，hooks 永远装不上（core.hooksPath 从未被写入，lefthook 从未安装）。

相关源码（scripts/install-lefthook.mjs @ 47f943859b）

锁获取的关键路径（acquireInstallLock，line 381 起）——先 openSync('wx') 创建并用 fd 记录 ownedStat，关闭句柄后再按路径 lstatSync 复查并比对 dev/ino：

const lockHandle = openSync(lockPath, 'wx', 0o600)          // line 388
let ownedStat
try {
  ownedStat = fstatSync(lockHandle)                         // exFAT：句柄打开时为接近 UINT64_MAX 的合成 ino
  writeFileSync(lockHandle, ownedRecord)                    // 记录 "PID UUID"
} finally {
  closeSync(lockHandle)                                     // exFAT：句柄关闭后，按路径 stat 的 ino 改变
}
const publishedStat = installLockStat(lockPath)             // lstatSync，line 400
if (
  publishedStat === undefined
  || !publishedStat.isFile()
  || publishedStat.isSymbolicLink()
  || publishedStat.dev !== ownedStat.dev
  || publishedStat.ino !== ownedStat.ino                    // exFAT 上恒不相等
) {
  throw lockOwnershipChangedError(lockPath)                 // → 错误二
}

stale 判定分支（同函数 catch 内，line 450，以下为源码原文）——锁已存在且属主 PID 不可达时要求人工恢复：

if (!lockOwnerIsAlive(owner)) throw manualLockRecoveryError(lockPath, 'stale')  // process.kill(pid, 0) 为 ESRCH → 错误一

根因分析

问题出在 macOS 的 exFAT 驱动报告的 file ID 不稳定，且变化点正好落在上述时序上：句柄仍打开时，fd 的 fstat 与按路径的 lstat 返回同一个（合成的、接近 UINT64_MAX 的）ino；closeSync 之后，按路径 lstat 得到的 ino 变成另一个小值。实测（exFAT 卷上新建文件）：

fstat(句柄打开时):  ino 18446744073709085000   ← 接近 UINT64_MAX 的合成值
lstat(句柄打开时):  ino 18446744073709085000   ← 与 fstat 一致
lstat(句柄关闭后):  ino 950466                 ← 不一致（dev 相同，仅 ino 变化）

acquireInstallLock 恰好在 closeSync 之后才做路径复查，因此 exFAT 卷上每次 install 都必然在取得锁之后的校验处抛 lockOwnershipChangedError，进程退出后锁文件被遗留给下一次运行——这就是两种错误交替出现的完整链条。（对照实验：同一探测在 APFS 卷上句柄关闭前后 ino 均不变。）

最小复现（复刻脚本的时序）：

const h = openSync(p, "wx", 0o600)
const f = fstatSync(h)
writeFileSync(h, "x")
closeSync(h)
lstatSync(p).ino === f.ino // APFS: true；macOS exFAT: false

想讨论 / 请教

1. 这种「fd 记录 inode + 路径复查」的防替换校验，是否可以考虑对不提供稳定 file ID 的文件系统降级？例如启动时探测一次 fstat/lstat 的一致性，不一致时退化为仅校验锁记录内容；或改用在该类文件系统上仍然稳定的所有权凭据。
2. 若判定为超出支持范围（要求 APFS/原生文件系统），是否值得在 README 或 troubleshooting 文档中注明，并在错误信息中提示 exFAT 场景？
3. 临时绕过（本机已验证）：CI=true pnpm install 可跳过 lefthook 安装（该脚本在 CI 环境下直接 return），依赖正常安装完成、退出码 0；或将仓库移至 APFS 卷（对照实验已确认 APFS 上该机制正常）。

以上分析如有误，欢迎指正。

[moonquake2004]

Cross-checked the report against master (scripts/install-lefthook.mjs @ 47f9438) — the mechanism is accurate:

acquireInstallLock (388–406) records the inode via fstatSync while the fd is open, then re-verifies by path with lstatSync after closeSync, throwing lockOwnershipChangedError on dev/ino mismatch. releaseInstallLock (359–377) relies on the same dev/ino + record-content double check. On a filesystem where fstat and lstat disagree, the acquire-time recheck (405–406) always fails and leaves the lock behind — the alternating stale/ownership loop you describe holds.

+1 on the degradation approach, and it costs no security:

• The 'wx' exclusive create already proves "I made this lock"; the record content (PID + UUID) is the ownership credential. The dev/ino recheck only guards the edge case of "same content, file replaced underneath" — on a filesystem without stable file IDs, dropping it loses nothing real.
• A light shape: probe once at startup whether fstat(open handle) vs lstat(after close) agree on ino (your minimal repro); if they disagree, skip the dev/ino check and validate the record content only. APFS/native filesystems keep current behavior — degradation is opt-in by detection, not by config.
• The existing DSH_TEST_LEFTHOOK_LOCK_WRITE_DELAY_MS hook shows this lock has test scaffolding; the same idea (a filesystem-identity-consistency probe hook) would let CI cover the degraded branch.

One general observation, in the same direction as the #1846 check-lifecycle discussion: any "validate/anti-replacement" logic should not depend on identity facts provided by the filesystem. Once the validation method itself relies on an unstable environmental fact, the failure migrates from the validated object to the validation. dsh-doctor's E6 tripwire picks anchors by the same principle — the anchor must be something stable that exists in the installed artifact.

[YuanyuanMa03]

Thanks for cross-checking the line numbers.

Detection over config makes sense to me too. One detail on the probe idea: it has to run in the lock file's directory, not /tmp — same filesystem matters. The minimal repro in the post works as the probe as-is.

I hit this on an external exFAT SSD (repo lives there for portability), so probably not a rare setup.

[moonquake2004]

Right — the probe must run on the same mount as the lock file; a /tmp probe on APFS would report "consistent" and never degrade. Using the minimal repro as the probe, in the lock directory, is the right shape.

Two small notes:

1. Probe once per process, cache the verdict. The mount's file-ID behavior is stable for its lifetime, so one probe (temp file in the lock dir → fstat → close → lstat → compare → unlink) at first lock acquisition is enough; no need to re-probe per install. It also keeps the hot path cheap.

2. The portability framing generalizes. Any filesystem without stable file IDs hits this — FUSE, some network/SMB mounts, and (as you found) exFAT on external SSDs. That makes the detection-based degrade worth shipping properly rather than documenting exFAT as out-of-scope: it's the same "validation must not depend on unstable environmental facts" principle, and it costs nothing on native filesystems.

If you want, I can sketch the concrete diff for acquireInstallLock (probe → skip dev/ino check when inconsistent) — small enough to post inline for upstream cherry-pick, same style as the #1739 patch we've been sharing.

[Electricitysheep]

exFAT 卷上 lefthook inode 校验永不成立——文件系统兼容坑（inode 语义在 exFAT 上不同）。和 #556（yaml UTF-8 自愈 bug）一起看，lefthook 在特殊环境的坑不少。

临时：仓库放回 APFS 卷，或跳过 lefthook。安装坑第 2 章有汇总：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/02-quickstart.md

[Cfomodz]

Why not just use the UUID record? Then it's filesystem independent as well.