fix: restore cache before installing runtime

.github/workflows/test.yaml

@@ -124,6 +124,58 @@ jobs:
             throw "Expected an extended-length store path, got: $storePath"
           }
 
+  runtime-cache-prime:
+    name: 'Prime runtime cache'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: ./
+        with:
+          version: '11.22.0'
+          runtime: node@24.19.0
+          cache: true
+
+      - name: 'Test: moving selector cache keys'
+        run: pnpm test
+
+  runtime-cache-hit:
+    name: 'Restore runtime cache'
+    needs: runtime-cache-prime
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # `pnpm runtime set` always fetches SHASUMS256.txt(.sig) and index.json
+      # from nodejs.org to verify the runtime, warm store or not, so the job
+      # cannot prove the restore happened by cutting the network. What it can
+      # prove is the key scheme: a second run of the same selector must land
+      # an exact hit on the key the first run saved under the resolved
+      # version, which only holds if the restore precedes the install.
+      - id: pnpm
+        uses: ./
+        with:
+          version: '11.22.0'
+          runtime: node@24.19.0
+          cache: true
+          install: false
+
+      - name: 'Test: runtime cache was restored'
+        env:
+          CACHE_HIT: ${{ steps.pnpm.outputs.cache-hit }}
+        run: |
+          set -e
+          if [ "${CACHE_HIT}" != "true" ]; then
+            echo "Expected a runtime cache hit, got: ${CACHE_HIT}"
+            exit 1
+          fi
+          actual="$(node --version)"
+          if [ "${actual}" != "v24.19.0" ]; then
+            echo "Expected node v24.19.0, got: ${actual}"
+            exit 1
+          fi
+        shell: bash
+
   runtime-node-pnpm11:
     # The whole premise of supporting v11 is that `pnpm runtime` works there.
     # Install pnpm v11, install a runtime through it, and run `pnpm install`.

README.md

@@ -18,7 +18,7 @@ If your `package.json` declares `devEngines.runtime`, the action picks up the ru
 | `version` | Version of pnpm to install: an exact version, a semver range (`^12.0.0`), or a dist-tag (`next-12`). Must resolve to v11 or newer. Optional when `packageManager` or `devEngines.packageManager` is set in `package.json`. |
 | `dest` | Where to store pnpm files. Defaults to `~/setup-pnpm`. |
 | `runtime` | Runtime spec, in `<name>` or `<name>@<version>` form (e.g. `node@22`, `node@lts`, `bun@latest`, `deno@2`). Supported names: `node`, `bun`, `deno`. When the version is omitted, falls back to `devEngines.runtime` in `package.json`, then to `lts` (for `node`) / `latest`. If the input itself is omitted, the action reads `devEngines.runtime` from `package.json`. |
-| `cache` | Cache the pnpm store directory. Default: `false`. |
+| `cache` | Cache the pnpm store directory and restore it before installing the runtime. Default: `false`. |
 | `cache-dependency-path` | Path(s) to the pnpm lockfile, used to compute the cache key. Default: `pnpm-lock.yaml`. |
 | `package-json-file` | Path to `package.json` (relative to `GITHUB_WORKSPACE`). Default: `package.json`. |
 | `install` | Run `pnpm install` after setup. Default: `true`. Set to `false` for jobs that only need pnpm itself (e.g. `pnpm audit`, lockfile-only regeneration). |
@@ -32,6 +32,7 @@ If your `package.json` declares `devEngines.runtime`, the action picks up the ru
 | `bin-dest` | Directory containing the `pnpm` / `pnpx` binaries. |
 | `runtime-name` | Name of the installed runtime, or empty string if none was installed. |
 | `runtime-version` | Resolved version of the installed runtime, or empty string if none was installed. |
+| `cache-hit` | Whether the pnpm store cache matched the exact primary key. |
 
 ## Usage
 
@@ -97,6 +98,10 @@ jobs:
     cache: true
 ```
 
+The cache is restored before the runtime is installed, so a cached runtime does
+not need to be downloaded again. Cache keys include both the requested runtime
+selector and the actual installed version.
+
 ### Skip `pnpm install`
 
 For jobs that only need pnpm itself — e.g. `pnpm audit`, lockfile-only regeneration — set `install: false`:

action.yml

@@ -39,7 +39,7 @@ inputs:
       project pins. Set the variable in the workflow to override.
     required: false
   cache:
-    description: Whether to cache the pnpm store directory
+    description: Whether to cache the pnpm store directory and restore it before installing the runtime
     required: false
     default: 'false'
   cache-dependency-path:
@@ -81,6 +81,8 @@ outputs:
     description: Name of the installed runtime (`node`, `bun`, or `deno`), or empty if none was installed
   runtime-version:
     description: Resolved version of the installed runtime, or empty if none was installed
+  cache-hit:
+    description: Whether the pnpm store cache matched the exact primary key
 runs:
   using: node24
   main: dist/index.js

package.json

@@ -3,7 +3,8 @@
   "scripts": {
     "build:bundle": "esbuild src/index.ts --bundle --platform=node --target=node24 --format=cjs --minify --outfile=dist/index.js",
     "build": "pnpm run build:bundle",
-    "start": "pnpm run build && sh ./run.sh"
+    "start": "pnpm run build && sh ./run.sh",
+    "test": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test src/cache-restore/keys.test.mjs"
   },
   "dependencies": {
     "@actions/cache": "^4.1.0",

src/cache-restore/index.ts

@@ -1,9 +1,13 @@
 import { isFeatureAvailable } from '@actions/cache'
 import { endGroup, startGroup, warning } from '@actions/core'
 import { Inputs } from '../inputs'
-import { runRestoreCache } from './run'
+import { RuntimeRequest } from '../install-runtime'
+import { finalizeCache, RestoredCache, runRestoreCache } from './run'
 
-export async function restoreCache(inputs: Inputs) {
+export async function restoreCache(
+  inputs: Inputs,
+  runtime: RuntimeRequest | undefined,
+): Promise<RestoredCache | undefined> {
   if (!inputs.cache) return
 
   if (!isFeatureAvailable()) {
@@ -12,8 +16,10 @@ export async function restoreCache(inputs: Inputs) {
   }
 
   startGroup('Restoring cache...')
-  await runRestoreCache(inputs)
+  const restoredCache = await runRestoreCache(inputs, runtime)
   endGroup()
+  return restoredCache
 }
 
+export { finalizeCache }
 export default restoreCache

src/cache-restore/keys.test.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { getCacheKeyPrefix, getPrimaryCacheKey } from './keys.ts'
+
+test('moving runtime selectors use the resolved version in the primary key', () => {
+  const prefix = getCacheKeyPrefix('Linux', 'x64', { name: 'node', version: 'lts' })
+  const previousKey = getPrimaryCacheKey(prefix, 'lockfile-hash', '22.22.0')
+  const currentKey = getPrimaryCacheKey(prefix, 'lockfile-hash', '24.13.0')
+
+  assert.notEqual(previousKey, currentKey)
+  assert.ok(previousKey.startsWith(prefix))
+  assert.ok(currentKey.startsWith(prefix))
+})
+
+test('the provisional restore key is never a key a runtime run saves under', () => {
+  const prefix = getCacheKeyPrefix('Linux', 'x64', { name: 'node', version: '24.19.0' })
+  const provisional = getPrimaryCacheKey(prefix, 'lockfile-hash')
+  const final = getPrimaryCacheKey(prefix, 'lockfile-hash', '24.19.0')
+
+  // An exact hit on the provisional key would stop the restore falling back
+  // to the prefix search that finds the versioned caches.
+  assert.notEqual(provisional, final)
+})
+
+test('without a runtime the provisional key is the final key', () => {
+  const prefix = getCacheKeyPrefix('Linux', 'x64', undefined)
+
+  assert.equal(
+    getPrimaryCacheKey(prefix, 'lockfile-hash'),
+    getPrimaryCacheKey(prefix, 'lockfile-hash', undefined),
+  )
+})

src/cache-restore/keys.ts

@@ -0,0 +1,28 @@
+import { createHash } from 'crypto'
+import type { RuntimeRequest } from '../install-runtime'
+
+export function getCacheKeyPrefix(
+  runnerOs: string | undefined,
+  architecture: string,
+  runtime: RuntimeRequest | undefined,
+): string {
+  const runtimeKey = runtime
+    ? hashCacheKeyPart(`${runtime.name}@${runtime.version}`)
+    : 'no-runtime'
+  return `pnpm-cache-${runnerOs}-${architecture}-${runtimeKey}-`
+}
+
+export function getPrimaryCacheKey(
+  keyPrefix: string,
+  fileHash: string,
+  resolvedRuntimeVersion?: string,
+): string {
+  const runtimeVersionKey = resolvedRuntimeVersion
+    ? `${hashCacheKeyPart(resolvedRuntimeVersion)}-`
+    : ''
+  return `${keyPrefix}${runtimeVersionKey}${fileHash}`
+}
+
+function hashCacheKeyPart(value: string): string {
+  return createHash('sha256').update(value).digest('hex')
+}

src/cache-restore/run.ts

@@ -4,8 +4,19 @@ import { getExecOutput } from '@actions/exec'
 import { hashFiles } from '@actions/glob'
 import os from 'os'
 import { Inputs } from '../inputs'
+import { RuntimeRequest } from '../install-runtime'
+import { getCacheKeyPrefix, getPrimaryCacheKey } from './keys'
 
-export async function runRestoreCache(inputs: Inputs) {
+export interface RestoredCache {
+  readonly fileHash: string
+  readonly keyPrefix: string
+  readonly restoredKey: string | undefined
+}
+
+export async function runRestoreCache(
+  inputs: Inputs,
+  runtime: RuntimeRequest | undefined,
+): Promise<RestoredCache> {
   const cachePath = await getCacheDirectory()
   saveState('cache_path', cachePath)
 
@@ -14,27 +25,36 @@ export async function runRestoreCache(inputs: Inputs) {
     throw new Error('Some specified paths were not resolved, unable to cache dependencies.')
   }
 
-  const primaryKey = `pnpm-cache-${process.env.RUNNER_OS}-${os.arch()}-${fileHash}`
-  debug(`Primary key is ${primaryKey}`)
-  saveState('cache_primary_key', primaryKey)
+  const keyPrefix = getCacheKeyPrefix(process.env.RUNNER_OS, os.arch(), runtime)
+  const provisionalKey = getPrimaryCacheKey(keyPrefix, fileHash)
+  debug(`Provisional cache key is ${provisionalKey}`)
+  saveState('cache_provisional_key', provisionalKey)
 
   // We don't need to download everything again if only one dependency changed
   // We can still re-use previous store to cache the rest of the unchanged dependencies
-  const restoreKeys = [
-    `pnpm-cache-${process.env.RUNNER_OS}-${os.arch()}-`
-  ];
-
-  let cacheKey = await restoreCache([cachePath], primaryKey, restoreKeys)
+  const restoreKeys = [keyPrefix]
 
-  setOutput('cache-hit', cacheKey === primaryKey)
+  const restoredKey = await restoreCache([cachePath], provisionalKey, restoreKeys)
 
-  if (!cacheKey) {
+  if (!restoredKey) {
     info(`Cache is not found`)
-    return
+    return { fileHash, keyPrefix, restoredKey: undefined }
   }
 
-  saveState('cache_restored_key', cacheKey)
-  info(`Cache restored from key: ${cacheKey}`)
+  saveState('cache_restored_key', restoredKey)
+  info(`Cache restored from key: ${restoredKey}`)
+  return { fileHash, keyPrefix, restoredKey }
+}
+
+export function finalizeCache(cache: RestoredCache, resolvedRuntimeVersion: string | undefined) {
+  const primaryKey = getPrimaryCacheKey(
+    cache.keyPrefix,
+    cache.fileHash,
+    resolvedRuntimeVersion,
+  )
+  debug(`Primary key is ${primaryKey}`)
+  saveState('cache_primary_key', primaryKey)
+  setOutput('cache-hit', cache.restoredKey === primaryKey)
 }
 
 async function getCacheDirectory() {

src/cache-save/run.ts

@@ -6,6 +6,17 @@ export async function runSaveCache() {
   const primaryKey = getState('cache_primary_key')
   const cachePath = getState('cache_path')
 
+  // The main step records the final key only once the runtime version is
+  // known. Without it the run failed before the key was settled, and the
+  // store was left in whatever state that failure produced. Saving it under
+  // the provisional restore key would publish that store under a key later
+  // runs match *exactly*, shadowing the complete cache held under the
+  // versioned key — and cache keys are immutable, so it would not heal.
+  if (!primaryKey) {
+    info('No final cache key was recorded, not saving cache.')
+    return
+  }
+
   if (primaryKey === state) {
     info(`Cache hit occurred on the primary key ${primaryKey}, not saving cache.`)
     return

src/index.ts

@@ -1,9 +1,15 @@
 import { setFailed, saveState, getState } from '@actions/core'
-import restoreCache from './cache-restore'
+import restoreCache, { finalizeCache } from './cache-restore'
 import saveCache from './cache-save'
 import getInputs, { Inputs } from './inputs'
 import installPnpm from './install-pnpm'
-import { resolveRuntimeRequest, installRuntime, InstalledRuntime, logSkippedRuntime } from './install-runtime'
+import {
+  getInstalledRuntimeVersion,
+  resolveRuntimeRequest,
+  installRuntime,
+  InstalledRuntime,
+  logSkippedRuntime,
+} from './install-runtime'
 import setOutputs from './outputs'
 import pnpmInstall from './pnpm-install'
 import pruneStore from './pnpm-store-prune'
@@ -24,18 +30,29 @@ async function runMain() {
   const result = await installPnpm(inputs)
   console.log('Installation Completed!')
 
-  let runtime: InstalledRuntime | undefined
   const request = resolveRuntimeRequest(inputs)
+  const restoredCache = await restoreCache(inputs, request)
+
+  let runtime: InstalledRuntime | undefined
   if (request) {
     runtime = await installRuntime(request, result.binDest)
     if (runtime === undefined) return
   } else {
     logSkippedRuntime()
   }
 
-  setOutputs(inputs, result.binDest, runtime)
+  if (restoredCache) {
+    // Falling back to the requested selector keeps the final key distinct
+    // from the provisional key the restore probed with. That key must never
+    // be written to: later runs match it exactly and would stop falling back
+    // to the prefix search that finds the versioned caches.
+    const resolvedRuntimeVersion = request
+      ? await getInstalledRuntimeVersion(request.name, result.binDest) ?? request.version
+      : undefined
+    finalizeCache(restoredCache, resolvedRuntimeVersion)
+  }
 
-  await restoreCache(inputs)
+  setOutputs(inputs, result.binDest, runtime)
 
   if (inputs.install) {
     pnpmInstall(inputs)