Semantics of vague version specs (latest / lts): should a shim ever block on the registry?

[tbontb-iaq]

Context

vp resolves package-manager and Node.js version specs on every shim invocation (select_core_tool → resolve_package_manager_tool → ensure_package_manager_bin). With an exact pin that is free. With a dist-tag (latest, lts, latest-10) it means a registry or nodejs.org round trip before the tool even starts.

Measured on vp 1.6.0, pnpm --version from a directory without a pin:

spec	1st call	2nd call	registry unreachable
latest, ~/.npmrc holds a token for the registry origin	5987 ms	5987 ms	hard error after 5 s
latest, no token in .npmrc	565 ms	54 ms	cached value, exit 0
exact pin pnpm@12.18.0	37 ms	37 ms	works

The cache bypass behind the first row is a bug, tracked in #3445. This discussion is about the semantics that make that bug matter.

Scope: two different layers

layer	source	can it be a tag?	strictness
project	package.json packageManager / devEngines, .nvmrc, .node-version	no — exact or range	must not be substituted: 24.6.3 means 24.6.3; download it if missing, fail if unavailable
vp	config.json defaultPackageManagerVersions, VP_*_VERSION, vp use	yes (latest, lts, latest-10)	open question — this thread

Project pins are Corepack-compatible and I am not proposing to change them. Tags only exist because vp added its own default/session layer, so their semantics are vp's to define.

My position

For a vague spec, "eventually the newest" is the right reading: being a patch or a minor behind costs nothing, while a slow command, a failing command, or a command that fails because the network is flaky costs real time. Vagueness should therefore be resolved asynchronously, and a tag lookup should never be a precondition for running an already installed tool.

Three candidate policies

policy	meaning of latest	shim behaviour	cost
P1 local-first	follows the tag, resolved only by vp	cache/installed only, zero network	can lag indefinitely if vp is never run
P2 bounded follow	follows the tag, checked on use	fresh cache → use it; expired → one lookup under a short budget (≤3 s); never installs from the shim; on failure falls back to cache/installed	one bounded request; a new version lands at the next vp-triggered refresh
P3 strict follow (today)	must resolve on use	blocking resolve + install; failure = command failure	the current behaviour: minutes in the worst case, hard failure offline

The rule I would like to see is "a shim may decide, but may not install": knowing that a newer release exists is harmless; downloading it while someone typed pnpm ls is not. Installation then belongs to vp paths.

Orthogonal pieces that help whichever policy wins:

• a dedicated short budget for optional metadata (connect ~1.5 s, total ~3 s, one attempt) instead of the generic 2 min / 30 s / three attempts;
• a stale-while-revalidate refresh, at most once per 24 h, spawned from vp commands — spawn_background_check_if_needed already does exactly this for self-update (lock, timestamp, VP_NO_UPDATE_CHECK), so the shim can stay dumb while freshness still happens;
• a resolution failure never turns into a command failure when an installed version exists (Package-manager shims hit the registry on every invocation when the registry origin has a credential, and lose the documented cache fallback #3445).

Questions

1. Which policy should latest / lts / latest-N have by default? I would pick P2.
2. Should the background refresh be on by default (interactive TTY, non-CI) or opt-in?
3. When a shim notices it is behind but does not install, should it print one line (pnpm 12.20.0 is available; run vp env refresh) or stay silent?
4. docs/guide/env.md documents both "cached for one hour" (line 102) and "re-resolve on each use" (line 191) — which of those survives?
5. Offline, with a project range (devEngines.packageManager: ^12) that is not installed: strict failure (Corepack behaviour) or the newest installed match?

Happy to send PRs either way — the uncontroversial part (#3445 plus the short budget) does not depend on this decision.

[fengmk2]

Thanks for separating the cache bug from the policy discussion. I’d address #3445 first by restoring caching and stale fallback with proper authentication isolation.

For the broader policy, I’d prefer local-first execution: when a floating spec has a known, usable installation, launch it immediately and refresh in the background. Even a bounded lookup adds unnecessary latency to routine commands.

The key is to track the resolved version separately from the ready-to-run version. A refresh should update the latter only after installation and verification succeed; failures should leave the working version available.

I would still allow synchronous installation on first use. Exact pins must remain strict, and fallback for a tag must use a version previously resolved for that tag and registry/auth context—not an arbitrary installed version.

This suggests two separate changes: fix authenticated caching first, then move floating-version updates off the launch path.