[Bug][Windows] koffi is load-bearing (session JSONL atomic writes, win32 process/acl) but fails late and confusingly under embedded Node

[nanami-0713]

Summary

On Windows, several core paths depend on the native FFI package koffi, loaded lazily at first use:

• dsh-session-persistence-jsonl: (await import("koffi")).default.load("kernel32.dll") → MoveFileExW, used for atomic session JSONL writes;
• dsh-win32-process and dsh-sandbox-windows-acl also bind through koffi.

koffi ships prebuilds for standard Node layouts, but under an embedded runtime with a different ABI (different NODE_MODULE_VERSION) — e.g. Electron's bundled Node — the prebuild fails to load. koffi's documented rescue hatch is a fallback binary at <resourcesPath>/koffi/<platform>_<arch>/koffi.node, which the embedder must arrange per platform itself.

Because the import is lazy, the failure surfaces far from its cause: a raw module-load error in the middle of normal operation (first session write / first process operation) rather than a startup-time diagnostic, and dsh web offers no actionable message.

What we would wish for

• fail fast (or at least log one clear line) when koffi cannot be loaded on win32, naming the ABI/embedded-Node cause and the resourcesPath workaround;
• or degrade gracefully (with a warning) where a safe fallback exists, instead of throwing at first use;
• and/or a short "embedding dsh web" note in the docs covering ABI requirements, koffi's fallback path, and recommended spawn settings — more and more community projects host dsh web inside Electron shells, and this is the single most surprising Windows pitfall.

Workaround we use today

When packaging our Electron shell for Windows we inject the win32-x64 koffi prebuild into the documented fallback location (resources/koffi/win32_x64/koffi.node via extraResources) and skip native rebuilds; with that in place, session persistence works. Making this contract official (or unnecessary) would make Windows packaging reliable for every embedder.

Environment

Windows x64 (10/11), dsh 0.1.x hosted under Electron's Node (ABI mismatch vs system Node), koffi win32-x64 prebuild injected via the resourcesPath fallback.