[Bug] macOS: npm install -g @deepseek-ai/dsh@0.1.6-alpha.1 aborts in koffi (ld: symbol(s) not found for architecture x86_64) — a stale @koromix/koffi-darwin-x64 forces a source build

[pysenic]

Environment

OS	macOS 13 (Darwin 22.6.0), Intel x86_64
Node / npm	v22.21.1 + npm 10.9.4 (also fails identically on v24.11.1 + npm 11.6.2)
Toolchain	cmake 3.31.0, AppleClang 14.0.3 (Command Line Tools), no ninja
Registry	https://registry.npmmirror.com
Starting point	@deepseek-ai/dsh@0.1.5-rc.2 installed globally and working

Symptom

npm install -g @deepseek-ai/dsh@0.1.6-alpha.1 aborts while building koffi@3.3.0:

info run koffi@3.3.0 install node_modules/@deepseek-ai/dsh/node_modules/koffi node ./cnoke.cjs -P . -D src/koffi --prebuild --release
>> Using CMake binary: cmake
>> Node: 22.21.1
>> Toolchain: native
>> Using local node-api headers
>> Running configuration
>> Running build
ld: symbol(s) not found for architecture x86_64
  "_napi_throw", referenced from: ...
  "_napi_typeof", referenced from: ...
  "_uv_poll_start", referenced from: ...
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make[2]: *** [Output/koffi.node] Error 1
make: *** [all] Error 2
Error: Failed to run build step
info run koffi@3.3.0 install { code: 1, signal: null }
npm ERR! code 1

Switching Node versions does not help (tried v24.11.1 and v22.21.1).

Root cause

koffi is a native FFI module whose install script only compiles from source as a fallback. koffi/cnoke.cjs decides with a one-liner:

async function checkPrebuild() {
  let proc = spawnSync(process.execPath, ["-e", "require(process.argv[1])", package_dir]);
  return proc.status === 0;
}

If require(<koffi package dir>) succeeds, the script returns immediately and uses the prebuilt binary shipped in the platform package @koromix/koffi-darwin-x64. Here it failed, so the script logged Failed to load prebuilt binary, rebuilding from source and went to CMake — where AppleClang failed to link koffi.node (the Node symbols _napi_* / _uv_* are unresolved, i.e. -undefined dynamic_lookup was not in effect).

The reason the require failed is that npm never re-downloaded @koromix/koffi-darwin-x64: a stale copy of that directory was already sitting in node_modules. Evidence from four failed runs:

Evidence	Failed runs	The successful retry
tarball download lines for @koromix/koffi-darwin-x64	0	yes (cache miss, downloaded)
placeDep line for that package	@koromix/koffi-darwin-x64@ with an empty version	normal
info run koffi@3.3.0 install	ran -> compiled -> failed	never ran

An empty version in placeDep plus no tarball fetch is npm's "this node already exists on disk" path: npm adopts the directory from the existing tree, skips the download, and never validates its contents. So a leftover/incomplete @koromix/koffi-darwin-x64 silently turns a prebuilt-binary install into a source build.

The reverse is equally confusing: rolling back to 0.1.5-rc.2 "succeeds" simply because npm decides koffi needs no rebuild, so the install script never runs — and the broken platform package stays on disk.

Workaround that fixed it

# stop the service first (it runs from the same global package)
pm2 stop dsh-web

rm -rf /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@koromix \
       /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/koffi

npm cache verify
npm install -g @deepseek-ai/dsh@0.1.6-alpha.1
pm2 start dsh-web

With the stale directories gone, npm actually downloads @koromix/koffi-darwin-x64 again (1.6 MB, koffi-darwin-x64-3.3.0.tgz — verified reachable on npmmirror), checkPrebuild() succeeds, and the install script returns without invoking CMake. 0.1.6-alpha.1 then installs cleanly.

Checks that back this up

• node -e "require('<...>/node_modules/koffi')" loads fine once the platform package is complete, so the prebuilt binary itself is not the problem.
• SESSION_FORMAT_VERSION is 3 in both 0.1.5-rc.2 and 0.1.6-alpha.1, and the llm-pi-ai / agent-default-model settings keys still exist in 0.1.6, so nothing in ~/.dsh had to be migrated.

If it still falls back to a source build

• Last resort: npm install -g @deepseek-ai/dsh@0.1.6-alpha.1 --ignore-scripts, then rebuild the packages that genuinely need it (e.g. npm rebuild -g node-pty).
• Or make the compile succeed: LDFLAGS="-undefined dynamic_lookup" npm install -g ... (treats the symptom, not the cause).

Suggestion for the project

This failure is only diagnosable through a log line that npm buries inside a generic command failed. It might be worth having the launcher (or the docs) detect a loadable koffi before use, or documenting "delete node_modules/@koromix and reinstall" for this class of npm tree corruption.

Related threads (different scenarios, same module): #293 (Windows, corrupt win32-x64 prebuilt), #136 (Termux, CMake required), #5949 / #5929 / #5784 (fs-ext has no prebuilt binaries), #197 / #2459 / #6461 (Windows koffi runtime issues).