fix(npm): select the Linux platform package by libc, not manifest order - #108

sequenceDiagram
  participant Facade as resolveBinary
  participant Detector as detectLibc
  participant Planner as planCandidates
  participant Filesystem

  Facade->>Detector: detect libc
  Detector->>Filesystem: read runtime and filesystem signals
  Filesystem-->>Detector: libc evidence
  Detector-->>Facade: gnu, musl, or undecided
  Facade->>Planner: plan platform candidates
  Planner-->>Facade: matching candidate order
  Facade->>Filesystem: verify executable
  Filesystem-->>Facade: executable status
  Facade-->>Facade: return binary or diagnostic

_{Comment @coderabbitai help to get the list of available commands.}

You're not wrong, and one of your two options is better than what I built. Splitting them, because they fail differently.

Ordering musl first: this works, and I under-weighted why

The reason it works is not ordering, it's that our musl targets are statically linked. This repo already leans on that — README.md: "two musl-static binaries, so one tag serves Alpine and Debian stages alike", and musl-resolve.Dockerfile accepts file reporting static as a pass.

A static binary has no PT_INTERP. There is no interpreter to be missing. @runner-run/linux-x64-musl runs on Alpine, Debian, the Deno hybrid image, and your laptop. So "always prefer musl on Linux" is correct on every host we ship for, in one line, with no detection:

• Conforming installer, glibc host → only the GNU package is installed, musl isn't there, we fall through to GNU. Nothing changes.
• Conforming installer, musl host → only musl. Nothing changes.
• Bun/Deno, both installed → musl wins, and musl runs everywhere. Bug fixed.

That is strictly simpler than four detection layers, and the layers buy one thing over it: on a glibc host with both installed, you get the dynamically-linked GNU build the package manager would have picked. That is a preference, not a correctness property.

Exec-and-fallback: the mechanism is sound, the diagnostic is what breaks

I expected to argue side effects here and I can't. When execve fails there is no child: spawnSync returns result.error with no status, nothing was spawned, nothing read stdin, no task ran. Gating a retry on result.error?.code === "ENOENT" && result.status == null is safe. EAFP is fine.

What it can't do is tell you why. ENOENT from spawnSync is the same errno for:

• the binary is missing,
• the binary exists but its ELF interpreter doesn't (our bug),
• the interpreter exists but a DT_NEEDED library doesn't.

So after the fallback also fails you know "both candidates failed to start", not "you have a glibc build on a musl host, install @runner-run/linux-x64-musl". You can still print a decent message by inspecting what's installed at that point — which is the same name-based reasoning, just moved after the failure instead of before it. That's a fair trade, not an obvious loss.

The narrower cost: resolveBinary() is a resolver with its own callers — musl-resolve.Dockerfile calls it directly to assert what the shim would pick. Fold the decision into the spawn and the only way to ask "which binary is right here" is to run something.

The "be more like Deno" version, taken seriously

denoland/deno:alpine doesn't detect anything. It ships a runtime that works on that image by carrying what it needs. Our equivalent is not smarter selection — it's not shipping the choice at all: drop linux-x64-gnu and linux-arm64-gnu, publish only the static musl builds for Linux, delete the libc field, and the entire failure class disappears. No detection, no fallback, no Bun/Deno double-download, half the Linux packages to build and publish.

The bill for that:

• glibc users get musl's allocator. For a spawn-detect-exec CLI I'd expect it in the noise, but I have not measured it and I'm not going to assert it without numbers.
• Anything relying on glibc-side behaviour — NSS, dlopen, locale — is gone. I don't think runner touches any of it, worth confirming.
• It's a published-package contract change, not a resolver change. Existing lockfiles pin @runner-run/linux-x64-gnu.

What I'd actually do

Not this PR — it implements the acceptance criteria in #106 as written, it's green, and swapping the strategy underneath it makes the diff unreviewable against its own issue.

As a follow-up, in order of how much they delete:

1. Ship only static musl for Linux. Deletes the problem instead of solving it. Needs a benchmark and a deprecation for the GNU package names.
2. Prefer musl, keep the diagnostic. Drop detectLibc to a tiebreak, order musl first because static-runs-anywhere, and keep the "only the wrong sibling is installed" error since that case has no working binary in either strategy. Roughly a net deletion.
3. Leave it as merged.

Say which and I'll open it. My preference is 1 if the benchmark supports it, 2 if it doesn't — and I'd rather find out with a measurement than by me asserting musl's malloc is fine.

Generated by Claude Code

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​runner-run@​0.12.2 ⏵ 0.24.1	+1			+3

View full report

Both fixed in defd065. Also: your Docker run went green, so the one part of this PR I couldn't execute is now verified on real hardware.

runner-run@0.12.2

The catalog asks for npm:runner-run@^0. 0.12.2 satisfies that, so once the lockfile recorded it, nothing ever moved it — ^0 spans the entire 0.x series, and bun has no reason to re-resolve a range that is still satisfied. Twelve releases went by underneath it.

It was never visible before because nothing in CI ran bun install. My chain added the first one, which is why a two-month-old resolution surfaced now rather than at some point last spring.

Nothing imports the package, but it is not dead weight either — site's scripts call it:

"prestart": "run build",
"deploy":   "run -s build wrangler:deploy",
"start":    "run wrangler:preview",

So it exists to put run on PATH, and every install was seeding node_modules/.bin/run with 0.12.2. Now npm:runner-run@^0.24, resolving to 0.24.1. It can still float within the minor, but it can no longer sit out a whole series.

One trap worth recording: bun update runner-run is not the fix. The workspace contains a package by that name (npm/facade), so the CLI matches the workspace member and rewrites the dependency to workspace:* — which points run at the facade template, whose optionalDependencies are empty until a release populates them. It "succeeds" and leaves you with a run that cannot resolve a binary. Editing the catalog range is the way.

cargo:test

Not the chain, and not env inheritance — I checked RUNNER_PM, RUNNER_DIR, RUNNER_GROUP_ACTIVE, GITHUB_ACTIONS, RUNNER_WARNED_ROOT, RUNNER_RUNNER, RUNNER_FALLBACK. A pre-existing race in nested_warnings.rs.

Both tests call nesting_project(), which builds the same path — runner-nested-<pid>, and the pid is shared because they are two tests in one binary. Each deletes that directory when it finishes, and cargo runs them on parallel threads. a_nested_runner_over_a_different_root_still_warns is the fast one: it spawns a single runner list, then deletes the shared directory. The other test is spawning runner run outer → just → a nested runner, so it is still mid-dispatch when the justfile disappears underneath it.

The resulting state reproduces the CI output exactly:

$ rm -f justfile && runner run outer      # what the surviving process sees
warn: runner.toml: unknown key `bogus` ignored: …
→ exec outer
Error: No such file or directory (os error 2)

No task named outer any more, so it falls through to exec, and there is no such command. Each test now gets its own tagged directory.

For honesty: I could not make it fail locally — 45 runs, 25 of them under saturated CPU. The window is small and your runner lost the coin flip. The shared path is plain in the source, though, and the reconstruction above matches the failure byte for byte.

Verified before pushing: full cargo test green, and the exact CI chain run end to end locally (fmt:check, cargo:lint, cargo:test, typecheck, test:facade — all ✓; just:lint-sh only omitted because shellcheck isn't in this container).

Generated by Claude Code

@claude, can you check on your end if "runner-run": "npm:runner-run@latest", would work instead of "runner-run": "npm:runner-run@^0.24",?

Tested it. latest works, and it fixes the staleness better than ^0.24 — but it breaks CI on every release of our own package. Recommend keeping ^0.24.

It resolves, and it self-heals. From a deleted lockfile it lands on 0.24.1. More interestingly, pointed at the stale lockfile from f6f6e89, a plain bun install drags it forward, which ^0 never did:

# stale lock holds runner-run@0.12.2, then bun install
  npm:runner-run@latest  ->  "runner-run@0.24.1"   ← self-healed
  npm:runner-run@^0      ->  "runner-run@0.12.2"   ← stayed put; the original bug

So as a staleness fix it is strictly better than what I pushed. ^0.24 only worked because 0.12.2 falls outside the range — it forces one upgrade and then goes quiet again inside 0.24.x.

The problem is --frozen-lockfile. A dist-tag is re-resolved on every install, so the moment published latest differs from the locked version, the frozen install refuses:

$ bun install --frozen-lockfile      # catalog: latest, lockfile behind
error: lockfile had changes, but lockfile is frozen
note: try re-running without --frozen-lockfile and commit the updated lockfile
$ echo $?
1

We publish this package. So the sequence is: release 0.25.0 → next CI run on every branch and PR fails at the install step of the verify chain → someone has to run bun install and commit the lockfile to unblock. A version range does not do that: with ^0.24 locked at 0.24.1, publishing 0.25.0 leaves the frozen install perfectly happy, it simply does not upgrade until the range is bumped.

The trade is: ^0.24 costs one deliberate edit per minor. latest costs a forced lockfile commit per release, and reds CI in the window between.

Unrelated finding while testing. Both the committed lockfile and a freshly regenerated one resolve the root's runner-run to runner-run@workspace:npm/facade, not the registry — the workspace member wins on name. node_modules/.bin/run still ends up 0.24.1, hoisted from site's copy, so nothing is broken today. But the root devDependency is not doing what it looks like it is doing, and if site ever dropped its copy, run at the root would become the facade template with empty optionalDependencies. Worth a separate look; I have not touched it.

Say the word if you want latest anyway and I will switch it — it is a one-line change, and dropping --frozen or adding a lockfile-refresh bot would cover the CI failure mode.

Generated by Claude Code

@claude RE:

The trade is: ^0.24 costs one deliberate edit per minor. latest costs a forced lockfile commit per release, and reds CI in the window between.

Mind updating the release checklist in the CHANGELOG.md to mention this?

Bit too verbose, this 0c793d6 update... Mind looking at the surrounding bulletlist, and following that kinda length?