[codetalcott]

Closes the gap CLAUDE.md recorded in #120: napi-mojo run kept its cached binary across a toolchain upgrade.

What was wrong

The cache key held the compiler command (pixi run mojo), and a pixi.lock or MAX bump leaves the command unchanged. After an upgrade, the next run therefore:

• skipped the compile, so the new compiler never saw the code;
• loaded the old binary against the new runtime. The binary finds libKGENCompilerRTShared through its RUNPATH, the pixi environment's lib/, and pixi upgrades that directory in place. Checked with readelf -d on a built host.node.

The fix

• The key now includes what <command> --version prints, e.g. Mojo 1.1.0 (8189361e). The build hash is part of that output, so moving from one nightly to the next also triggers a rebuild.
• If the compiler runs but reports no version, the cache is off for that run, with a warning, rather than keying on nothing.
• If the compiler can't run at all, there's no warning, because the compile itself then fails with the usual advice.

Cost is one probe per run. Measured locally, cached runs went from 155–192 ms to 212–252 ms: about 55 ms through pixi run, 17 ms calling the binary directly.

Tests

• Two new stub-compiler tests in tests/cli.test.js; the stub now answers --version from a file:
  • a changed version recompiles;
  • a compiler that can't report its version is never served from the cache.
• Each of the three new rules was reverted once and its test failed.
• Real toolchain, with a --mojo wrapper that changes only the reported version:
  • unchanged version: 212 ms, binary untouched;
  • changed version: 2.2 s, binary rewritten.
• The CI "Host-mode program with library include roots" step passes locally with the probe in place.
• npm test: 837 passed, 12 skipped. check-doc-samples, generate-rules-extract --check and sync-versions --check pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_013tXV7MkRfP97g5hPfNNXHC

---

Generated by Claude Code