Native modules
node-pty and Codex's bundled native runtime both need platform-correct installation, ABI-matched rebuilds, and correct asar-unpacking to work in a packaged build.
Two native dependencies need special handling: node-pty (terminal/PTY support) and the native runtime @openai/codex-sdk bundles as a per-platform optional package.
Electron ABI mismatch
node-pty is a compiled native module and must match Electron's Node ABI, not just your system Node.js version. A mismatch (commonly after an Electron or Node version bump) causes it to fail loading — see node-pty failures. Fix it with:
npm run rebuild:native
npm run native:checkPer-platform installation
npm ci on Linux never installs Windows or macOS variants of these native dependencies — cross-building a Windows or macOS package from Linux would silently ship the wrong or missing native binaries. Build each platform on its own OS. This is also why the Windows .exe icon step (rcedit, via scripts/after-pack-set-icon.js) needs Windows or Wine to run.
Execute permissions
node-pty's native spawn-helper binary can lose its execute bit during install on macOS or Linux — scripts/fix-native-permissions.js restores it, and runs automatically via postinstall and again before every macOS packaging build.
asarUnpack
Both node-pty's compiled binaries and any @openai/codex-*-* optional package are explicitly excluded from app.asar in electron-builder.yml, because native executables inside an asar archive can't be spawned directly by the OS — see Packaging.