Node 24 binary missing on Windows after install (proto::locate::missing_executable)

[rhuanbarreto]

Environment

• proto version: 0.56.4
• OS: Windows Server 2025 (GitHub Actions windows-latest)
• Node version requested: ~24 (resolved to 24.14.0)
• .prototools: node = "24"

Problem

When installing Node 24 on Windows via moonrepo/setup-toolchain, proto reports the installation as successful but the actual node.exe binary is never written to disk. The warnings are emitted during symlink creation but the install is not marked as failed:

[ WARN ] proto_core::flow::link  Unable to symlink binary, source file does not exist
  tool="node"
  source="C:\Users\runneradmin\.proto\tools\node\24.14.0\node.exe"
  target="C:\Users\runneradmin\.proto\bin\node.exe"

[node] Node.js 24.14.0 installed

After this, any attempt to use node via the proto shim fails:

Error: proto::locate::missing_executable

  × Unable to find an executable for Node.js, expected file
  │ ~\.proto\tools\node\24.14.0\node.exe does not exist.

Reproduction

1. Create .prototools with node = "24"
2. Run moonrepo/setup-toolchain on windows-latest with auto-install: true
3. Try to run node --version

Expected behavior

Either:

• The Node 24 binary should be properly downloaded and installed on Windows
• Or the installation should fail with an error (not succeed with warnings) so the CI step fails early with a clear message

Workaround

Pinning to node = "22" (LTS) works correctly on Windows.

CI log reference

Full log: https://github.com/archgate/cli/actions/runs/25657982746/job/75311030982

[milesj]

@rhuanbarreto This is confusing since I've been testing with v24 non-stop for the past week on this PR: #996

Works just fine on all operating systems.

Can you ls the directory to see what's unpacked?

[rhuanbarreto]

@milesj Thanks for looking into this. You're right — proto install node 24 works fine locally on my Windows machine too (proto 0.56.4, Windows 10 x86_64, Git Bash). The issue was specific to GitHub Actions windows-latest runners using moonrepo/setup-toolchain.

Here's what we observed in the CI logs:

Run 1 (with cache hit):

Cache hit for: moonrepo-toolchain-v3-win32-x64-368f3382...
[ WARN ] proto_core::flow::link  Unable to symlink binary, source file does not exist
  tool="node"
  source="C:\Users\runneradmin\.proto\tools\node\24.14.0\node.exe"
[node] Node.js 24.14.0 installed

Run 2 (after deleting ALL caches — fresh install, no cache):

Installing proto tools
[ WARN ] Unable to symlink binary, source file does not exist
  tool="node" source="C:\Users\runneradmin\.proto\tools\node\24.14.0\node.exe"
[node] Node.js 24.14.0 installed

Same result with a completely fresh install — no cache involved. The binary is never written to disk. The postinstall script then fails with proto::locate::missing_executable.

This was on windows-latest (Windows Server 2025, 10.0.26100) with proto 0.56.4 installed by moonrepo/setup-toolchain@261c62cb.

We worked around it by pinning to node = "22" in .prototools for our CI. If you can't reproduce it, it might be something specific to the Windows Server 2025 runner image or the setup-toolchain cache interaction. Happy to provide full CI log links if helpful:

• Failing run (fresh install, no cache): https://github.com/archgate/cli/actions/runs/25666413379/job/75340007014
• Successful run (after pinning node 22): https://github.com/archgate/cli/actions/runs/25666567201/job/75340463113

[rhuanbarreto]

To add more context on the root cause analysis we did:

We traced the regression to commit d1f5e10 ("fix: Audit 04/16 (#993)"), which upgraded starbase_archive from 0.12.7 → 0.13.0 and starbase_utils from 0.12.10 → 0.13.1.

Specifically, starbase_archive 0.13.0 includes commit 5163626 ("security: Fix a zip slip vulnerability") which rewrites the path sanitization logic in tar.rs (adding safe_entry_path). While zip.rs wasn't directly changed, the starbase_utils 0.13.1 upgrade changed the download flow in net.rs:

// OLD (0.12.10): always creates + truncates
let mut file = fs::create_file(dest_file)?;

// NEW (0.13.1): creates OR opens existing without truncating
let mut file = fs::create_file_if_missing(dest_file)?;
// then truncates inside the write closure
fs::truncate_file_handle(dest_file, &mut file)?;

The timing evidence supports this: all CI runs using cache key ...18f264... (built before the audit commit) passed. After the cache key rotated to ...368f3382... (built with the new starbase versions), every Windows run failed. The old cache had a working Node 24 binary from the previous starbase version; the new cache (and fresh installs) produced an empty install directory.

This might explain why you can't reproduce it locally — if your local proto was built from a branch that doesn't include the starbase 0.13.x upgrade, or if the Windows Server 2025 runner image handles file creation/truncation differently than desktop Windows.

[milesj]

Amazing debugging. I'll see what I can do.

Those archive/net changes were supposed to solve race conditions... lol.

[milesj]

This is what Claude had to say. I kind of agree with it, since I've been using Node 24 on fresh boxes. I'll try and reproduce further.

---

Verifying the investigation in issue #1006

Context

rhuanbarreto reported that on windows-latest GitHub Actions runners (Windows Server 2025) installing Node 24 via proto + moonrepo/setup-toolchain "succeeds" but node.exe is never written to disk. They git-bisected the regression to commit d1f5e10e ("fix: Audit 04/16 (#993)") and hypothesised that the change to starbase_utils::net::download_from_url_with_options (now using create_file_if_missing + truncate_file_handle instead of create_file) is the root cause. They also asserted that starbase_archive 0.13.0 introduced a zip-slip fix that added safe_entry_path in tar.rs.

The user has asked us to verify whether the investigation is correct before acting on it.

Verification

Claim 1 — d1f5e10 bumped starbase_archive 0.12.7 → 0.13.0 and starbase_utils 0.12.10 → 0.13.1

CORRECT. Confirmed in the Cargo.lock/Cargo.toml diff of d1f5e10e (Cargo.toml:50-66). The commit also bumped starbase_sandbox (dev only) and tokio 1.52.0 → 1.52.1.

Claim 2 — starbase_archive 0.13.0 added safe_entry_path / rewrote tar.rs path sanitisation

INCORRECT. The published source of starbase_archive 0.13.0 is byte-identical to 0.12.7 across every file (archive.rs, tar.rs, zip.rs, gz.rs, all *_error.rs, tree_differ.rs, lib.rs). Only Cargo.toml differs (its own version + dev-dep on starbase_sandbox). safe_entry_path already existed at tar.rs:199 in 0.12.7 — grep across 0.12.4/5/6/7 shows it was actually introduced in 0.12.7. So this version bump cannot have changed any archive-extraction behaviour.

Claim 3 — starbase_utils 0.13.1's net.rs changed how the download file is created

CORRECT as far as the diff goes. The change is:

• 0.12.10: fs::create_file(dest_file)? (atomic OpenOptions::create + truncate), then file.lock() unconditionally, write, then file.unlock().
• 0.13.1: fs::create_file_if_missing(dest_file)? (write-create, no truncate), then acquire_exclusive_lock gated by feature = "fs-lock", then truncate_file_handle (= set_len(0) + seek(0)), then write, then release_lock gated on the same feature.

create_file_if_missing is OpenOptions::new().write(true).create(true).open(path) — no truncate flag. truncate_file_handle does file.set_len(0) followed by file.seek(SeekFrom::Start(0)).

Claim 4 — That net.rs change is the root cause of the Windows Server 2025 silent-empty-install

PLAUSIBLE BUT NOT VERIFIED, and important caveats below.

• proto declares starbase_utils with default-features = false, features = ["json", "miette", "net", "toml"] (Cargo.toml:62-68). It does not enable fs-lock. So in the compiled proto binary:
  • The 0.12.10 path was effectively: create_file (open+truncate atomically) → file.lock() was still called because in 0.12.10 the lock call was not feature-gated → write → file.unlock().
  • The 0.13.1 path is: create_file_if_missing → no lock at all (gated away) → truncate_file_handle (set_len(0)+seek) → write → no unlock.
• So the real behavioural delta in proto specifically is: from "atomic open+truncate + always-lock" to "open(no truncate) + set_len(0) + seek + no-lock".
• I cannot identify a deterministic Win32 reason that this two-step truncate-via-handle would silently produce a 0-byte or stale archive while still returning Ok(()). OpenOptions::write(true).create(true) maps to CreateFile(GENERIC_WRITE, OPEN_ALWAYS), which grants the access needed for SetEndOfFile. The download function's error path also unconditionally remove_files on do_write failure, so a partial write wouldn't survive.
• More importantly, an empty/stale archive would either (a) fail checksum verification in install.rs:399-432 — node's WASM plugin supplies checksum_url, so this is a real check — or (b) fail to parse as a zip at ZipUnpacker::new. Neither failure would be silent.

Claim 5 — Timing/cache-key evidence

CORRECT but doesn't distinguish between (a) net.rs being the cause and (b) something else in d1f5e10e being the cause. The cache key in moonrepo/setup-toolchain is derived from the proto version, so any change in d1f5e10e rotates the key — not just net.rs.

Things that don't fit the net.rs hypothesis

• Node 22 works on the same runner with the same proto build. Node 22 Windows uses the exact same download → unpack code path with the same archive layout (node-vXX.X.X-win-x64.zip). If net.rs truly broke downloads on Windows Server 2025, Node 22 should fail too. The fact that pinning to 22 "fixes" it is suspicious — it could just be a stale cache from before the audit commit that happens to still work for 22.
• starbase_archive source didn't change at all in d1f5e10e, so the extraction step is identical.
• d1f5e10e also added HTTP read/connect timeouts (read_timeout(5min), connect_timeout(1min)) and changed netrc handling. A read-timeout mid-stream on a slower Windows Server 2025 runner could truncate a download — but again, that would fail checksum verification, not silently succeed.

Verdict

The investigation correctly identifies the commit (d1f5e10e) and one of the two relevant source-level changes (the net.rs download flow). The starbase_archive/safe_entry_path portion is wrong on the facts. The net.rs root-cause hypothesis is plausible but unproven, and there's a gap (Node 22 vs Node 24 on the same code path) that the hypothesis doesn't explain.

Recommended next steps

Before believing or acting on the bisection, gather one piece of missing evidence and then narrow the suspect set:

1. Get a directory listing from a failing CI run. Ask rhuanbarreto to add dir C:\Users\runneradmin\.proto\tools\node\24.14.0\ (or ls) right after the proto install step on a failing run. We need to know whether the directory is completely empty (download/extract never produced anything) or contains other extracted files minus node.exe (an extraction-skip bug). This single piece of evidence points the investigation in opposite directions:

   • Completely empty → download or zip-open silently produced nothing usable.
   • Other files present, only node.exe missing → an extraction-time path/skip bug, almost certainly not in net.rs.

2. Bisect inside d1f5e10e rather than just to it. The commit contains four behavioural changes that all rotate the cache key: starbase_utils net.rs flow, HTTP read/connect timeouts, netrc init handling, and OCI/data protocol rewrites in warpgate. The cleanest test is to publish a branch that keeps the rest of d1f5e10e but pins starbase_utils = "0.12.10" and starbase_archive = "0.12.7" and runs the user's CI repro on windows-latest. If that branch passes, the regression is in starbase; if it fails, it's elsewhere in d1f5e10.

3. Add a defensive post-install check in proto. Independently of root cause, install_from_prebuilt returns Ok even when the unpack produced zero files, and Tool::is_installed treats the existence of the product directory as proof of installation. After unpack_raw succeeds, we should verify the product directory is non-empty (or at least contains something resembling the expected entry point) and fail the install with a clear error otherwise. This converts the "succeeds with warning" symptom into a hard failure that surfaces correctly in CI.

Critical files referenced

• Cargo.toml — dependency declarations
• crates/core/src/flow/install.rs — install_from_prebuilt, the call into net::download_from_url_with_options and archive::unpack_raw
• crates/core/src/utils/archive.rs — thin wrappers around starbase_archive
• crates/core/src/tool.rs:209 — is_installed, which only checks dir existence
• crates/warpgate/src/clients/http.rs:140-160 — the other behavioural change in d1f5e10e (HTTP timeouts)

Verification of any eventual fix

• Reproduce on windows-latest GitHub Actions runner (cannot be reproduced on macOS/Linux).
• Use the user's failing scenario: .prototools with node = "24" + moonrepo/setup-toolchain with auto-install: true → node --version.
• For the defensive-check fix specifically: a unit test that calls install_from_prebuilt against a fixture archive containing zero files should now return Err(ProtoInstallError::…) rather than Ok.