test: build the native binding when it is missing, warn when it is stale

[flora131]

A fresh checkout or a new git worktree has no compiled native binding, and the resulting failure names the wrong subsystem. It was convincing enough that I twice diagnosed it as a broken main while working in this repo.

The trap

npm ci --ignore-scripts is the mandated install (AGENTS.md) and the natives workspace has no install hook, so nothing builds packages/natives/native/*.node.

Since the in-process subagent runner landed, packages/subagents reaches the Rust control plane through a static import. A missing binding therefore throws while the module graph is still loading and takes roughly twenty root unit and integration files with it. .github/workflows/test.yml already says so:

the bundled subagent extension fails to load at import without a binding. That takes the root unit and integration suites down with it, not just the in-process runner tests.

The errors name whatever imported the extension — workflow-stage-bundled-resources, the in-process runner suites — not the missing .node. So it reads like a regression somewhere else entirely.

The generated napi-rs loader makes it worse:

Cannot find native binding. npm has a bug related to optional dependencies … Please try npm i again after removing both package-lock.json and node_modules directory.

That advice cannot work here. With --ignore-scripts, reinstalling never produces the binding, so following it loops. native/index.js is generated (@ts-nocheck) and would lose a hand edit at the next napi artifacts, so the correct instruction has to live at test setup.

What this adds

A vitest globalSetup that runs before any file is collected:

State	Behaviour
present and current	returns after one stat — CI (which builds in an explicit step first) and warm worktrees pay nothing
missing	prints what it is doing and builds (~35 s, once per worktree)
older than crates/	warns and runs anyway
build failed	fails with the Rust prerequisite, the paths searched, and the command that actually works

Staleness only warns. git checkout rewrites mtimes, so a timestamp is weaker evidence than a version sentinel, and blocking a suite on weak evidence is worse than running one build too few.

Prior art

Shape borrowed from can1357/oh-my-pi's packages/natives/native/loader-state.js, which solves the same problem for its runtime loader: report every candidate that was tried, give the exact command for the context you are actually in, and let a dev tree keep running on a stale binding rather than hard-failing while a rebuild is pending (isWorkspaceLoad).

Two deliberate differences:

• This runs at test setup, not load time, so it can repair the missing case instead of only describing it.
• Staleness is a timestamp comparison, because our .node carries no embedded version sentinel. oh-my-pi embeds __piNativesV<version> and uses it to distinguish disk stale ("reinstall") from process stale ("restart — reinstalling changes nothing"). Adding an equivalent sentinel to crates/atomic-natives would be a strictly better signal than mtimes and is worth doing separately.

Verification

All four paths exercised directly:

present + fresh     1.98s, silent
stale               WARNING printed, 23 tests still pass
missing             builds, then 7 tests pass in the file that used to die at import
missing, no cargo   fails naming rustup.rs and the build command

• npm run check — exit 0
• npm run test:unit — 617 files, 5824 passed, 2 skipped
• npm run test:ci-contracts — 6 files, 41 tests, exit 0

Also

DEV_SETUP.md claimed a missing binding "silently degrades" and failed "several packages/coding-agent tests (bash-pty-native, search-tool-*, hashline-tools)". That predates the static import and is corrected here — the CLI does still degrade gracefully, but the suites do not.

No package changelog entry: per AGENTS.md, repository tooling is infrastructure-level and does not change shipped package behaviour.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Greptile Summary

The native test setup now checks whether the generated loader can load a binding for the current host and rebuilds the binding when it cannot. An isolated test with an unusable native artifact confirmed that setup rebuilds the host binding before the CI test project runs successfully.

Confidence Score: 5/5

No blocking failure remains.

The host-binding recovery path was exercised with an invalid native artifact and the configured CI test project completed after rebuilding a usable binding.

T-Rex Logs

What T-Rex did

• Validated that the retained generated loader previously failed on an invalid artifact with file too short, and that after the changes the Vitest global setup prints a message indicating it is building now, with the CI project passing.
• Concluded that no additional work is required and recommended preserving the current load-attempt behavior rather than reverting to a filename-only .node scan.
• Verified that runtime.ts exports fileExists but not existsSync, readdirSync, or statSync, and that the tests pass with Vitest 4.1.10 on Node 24.19.0.
• Observed that no primary workspace files were changed; only artifact-contained validation files were created.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "test(natives): detect a binding by loadi..." | Re-trigger Greptile}