Windows 首次 pnpm install 时 lefthook postinstall 报 yaml: invalid leading UTF-8 octet（自愈型 bug，附根因线索）

[Chris-Xie369]

Windows 全新 clone 后首次 pnpm install，lefthook postinstall 报 yaml: invalid leading UTF-8 octet

复现、预期与验收

• 复现步骤：Windows 11 全新 clone（git 2.x）+ pnpm install（node 24.15.0、pnpm 11.7.0），触发 postinstall node scripts/install-lefthook.mjs
• 实际结果：lefthook.cmd install --force 报 Error: yaml: invalid leading UTF-8 octet，postinstall 退出码 1（--ignore-scripts 可绕过）
• 预期结果：首次安装 hooks 成功
• 根因线索（已排查）：
  1. lefthook.yml 本身是合法 UTF-8（hexdump 开头 # Git ho 纯 ASCII；lefthook dump 可正常解析同一文件）——错误信息是误导性的，问题不在仓库配置文件
  2. 失败发生在"首次初始化"状态：core.hooksPath 指向 .git/dsh-hooks（此时目录里只有 .dsh-lefthook-owned ownership marker，无 hook 文件），且 .git/info/lefthook.checksum 尚不存在
  3. 一旦 lefthook 成功运行过一次（创建 checksum + 安装 hooks），问题永久消失——重跑 node scripts/install-lefthook.mjs 完全正常（sync hooks ✔️）。疑似 lefthook 2.1.9 在 Windows 上读取未初始化的内部状态时的 bug
  4. CI 不踩此路径（CI 环境 hooks 已存在或有不同状态），故未在现有测试覆盖
• 环境：Windows 11、node v24.15.0、pnpm 11.7.0、lefthook 2.1.9（postinstall 拉取）、git 2.4x（MSYS）
• 验收条件：Windows 全新 clone 后 pnpm install postinstall 一次通过（或脚本给出明确诊断而非误导性 YAML 错误）

[Chris-Xie369]

Update: fix candidate prepared on a fork

I prepared a fix candidate on my fork. Since this repo doesn't accept external PRs (issues are disabled, PR count is 0), I'm attaching the details here so the team can cherry-pick or verify it.

Branch: Chris-Xie369/deepseek-harness → fix/windows-lefthook-first-install (single commit 31bf973e33)

Change: bump lefthook ^2.1.9 → ^2.1.10 (package.json + pnpm-lock.yaml only).

Why 2.1.10: the v2.1.9...v2.1.10 diff swaps in go.yaml.in/yaml/v4 (YAML library upgrade) and includes a Windows binary-extension fix — the only plausible fix vectors for the misleading yaml: invalid leading UTF-8 octet error on first Windows install.

Honest limitation: the error self-healed on the reporting machine before I could capture a reproduction, so this is a version-bump candidate rather than a verified fix. Three reset scenarios (fresh marker-only dsh-hooks, full state wipe, true fresh clone + pnpm install on 2.1.9) all installed cleanly locally, which suggests the trigger is an environment-specific Go/yaml edge case rather than repo config.

If anyone with a machine that reproduces the failure can test lefthook@2.1.10, that would confirm the fix. Happy to rebase the branch on request.