Source checkout: every run fails with Cannot find module …/node-addon-system-<platform>/bin/system.node after pulling the fs-ext → node-addon-system migration（源码检出拉取 flock 迁移后运行即失败，缺 bin/system.node）

[3rd-Musketeer]

Environment

• Clone of deepseek-ai/deepseek-harness, HEAD 5dda764ed3 (dsh 0.1.5-alpha.1) — checked out before Sep 7, then git pull + pnpm install
• macOS 15, arm64; Node v24.18.0; pnpm 11.7.0
• Running from the source workspace (not the npm package)

Symptom

Every harness run fails at startup:

Cannot find module '<repo>/native/system/packages/darwin-arm64/bin/system.node'
Require stack:
- <repo>/native/system/packages/entry/src/flock.ts

The checkout passed the documented First-time setup (pnpm install + pnpm run typecheck), so nothing signaled that a build step was missing until the first run.

Root cause

1. d927cbff99 (Sep 7) replaced fs-ext with the in-repo @deepseek-ai/node-addon-system family — motivated by the fs-ext NAN compile failures (Windows 更新后源码运行失败：fs-ext@2.1.1 在 node-gyp 阶段无法完成安装 （Windows source install fails at fs-ext@2.1.1 / node-gyp after recent update） #5784, 0.1.3.Alpha.2，引入了 fs-ext@2.1.1 无预编译二进制，强制本地 MSVC 编译 #5929, Windows install requires the full MSVC toolchain for fs-ext, which win32 never actually calls / Windows 安装被迫为从未调用的 fs-ext 拉起整套 MSVC 工具链 #5945). Reasonable move: npm consumers are unaffected, since the published platform tarballs ship bin/.
2. Inside the workspace, the entry package's platform optionalDependencies are workspace:* links to native/system/packages/<platform>/, and packages/*/bin/ is gitignored by design — so on a source checkout bin/ stays empty until you build it.
3. pnpm install succeeds silently, and the setup-completion gate in docs/development.md (typecheck) never touches native artifacts. A machine set up before Sep 7 and pulled since therefore looks healthy until the first run.
4. The required step — pnpm run build:native-system — is documented only in native/system/README.md (Development) and the Sep 7 agent note ("Source builds explicitly compile the host addon before repository tests and builds that need it"). It is absent from the root setup docs, and the runtime MODULE_NOT_FOUND carries no pointer to it.

Workaround (verified)

pnpm run build:native-system   # from repo root; builds <platform>/bin/system.node

After this, native/system's flock suite passes 23/23 and runs start normally again. (Running that suite also needs pnpm -C native/system run build:test-oracle first, or the 4 C-oracle tests fail.)

Any pull that touches native/ requires re-running the build.

Suggestions — any one of these closes this class of report:

1. Add the host-addon build to First-time setup in docs/development.md, plus a "re-run after pulls touching native/" note.
2. An install-time or doctor-style check verifying that the host platform package's prebuilds.json-declared files exist, failing with the exact fix command.
3. An actionable runtime error: when the flock binding is missing on a source checkout, name pnpm run build:native-system in the message.

Happy to send a docs PR for (1) if that's useful.

---

环境：macOS arm64 源码检出（Sep 7 之前克隆，pull 至 0.1.5-alpha.1 / 5dda764ed3）；Node 24.18.0 / pnpm 11.7.0。

现象：每轮运行启动即失败，报 Cannot find module '…/native/system/packages/darwin-arm64/bin/system.node'（require 栈指向 entry/src/flock.ts）。文档规定的初始化（pnpm install + pnpm run typecheck）全部通过，没有任何信号提示缺构建步骤。

原因：d927cbff99（9 月 7 日）用仓库内 node-addon-system 替换 fs-ext（动机即 #5784 / #5929 / #5945 的 fs-ext 编译问题；npm 用户不受影响，发布 tarball 自带 bin/）。但 workspace 内平台包是 workspace:* 链接、packages/*/bin/ 按 design 不进 git，源码检出装完依赖后 bin/ 为空；必需的 pnpm run build:native-system 只写在 native/system 子目录 README 和 agent note 里，根目录 setup 文档没有，运行时报错也不指路。

解法（已验证）：仓库根目录 pnpm run build:native-system；跑 flock 测试套件前先 pnpm -C native/system run build:test-oracle。凡 pull 涉及 native/ 都要重跑构建。

建议（三选一即可）：setup 文档补上该步骤；或 install / doctor 时校验宿主平台 prebuilds.json 声明的文件并给出修复命令；或运行时报错直接带上 pnpm run build:native-system。第 1 项我可以直接提 PR。