fix: version matching and tool cache keys for build-metadata tags

.github/workflows/ci.yml

@@ -120,11 +120,6 @@ jobs:
           #   runner: macos-latest
           #   installer: pkg
 
-          # --- macOS AMD64 ---
-          - name: macos-amd64 (archive)
-            runner: macos-15-intel
-            installer: archive
-
           # --- Windows AMD64 ---
           - name: windows-amd64 (archive)
             runner: windows-latest

README.md

@@ -103,7 +103,7 @@ This installs the latest nightly build of Elide and adds it to the `PATH`.
 
 ## Installers
 
-The `installer` input controls how Elide is installed. The default (`archive`) downloads a prebuilt archive from the Elide CDN and caches it using the GitHub Actions tool cache.
+The `installer` input controls how Elide is installed. The default (`archive`) downloads a prebuilt archive from the Elide CDN (or, for pinned nightly/build-metadata versions, the matching GitHub release asset) and caches it using the GitHub Actions tool cache.
 
 | Installer | Platforms | Description |
 |---|---|---|

__tests__/install-apt.test.ts

@@ -86,7 +86,7 @@ describe('install-apt', () => {
     ])
 
     expect(result.elidePath).toBe('/usr/bin/elide')
-    expect(result.version.tag_name).toBe('1.0.0')
+    expect(result.version.tag_name).toBe('latest')
   })
 
   it('should map aarch64 to arm64 for apt', async () => {

__tests__/install-msi.test.ts

@@ -117,7 +117,7 @@ describe('install-msi', () => {
     const result = await installViaMsi(options)
 
     expect(result.elidePath).toBe('C:\\Elide\\bin\\elide.exe')
-    expect(result.version.tag_name).toBe('1.0.0')
+    expect(result.version.tag_name).toBe('latest')
     expect(result.version.userProvided).toBe(false)
   })
 

__tests__/install-pkg.test.ts

@@ -117,7 +117,7 @@ describe('install-pkg', () => {
     const result = await installViaPkg(options)
 
     expect(result.elidePath).toBe('/usr/local/bin/elide')
-    expect(result.version.tag_name).toBe('1.0.0')
+    expect(result.version.tag_name).toBe('latest')
     expect(result.elideBin).toBe('/usr/local/bin')
     expect(result.elideHome).toBe('/usr/local/bin')
   })

__tests__/install-rpm.test.ts

@@ -109,7 +109,7 @@ describe('install-rpm', () => {
       '/tmp/elide.rpm'
     ])
     expect(result.elidePath).toBe('/usr/bin/elide')
-    expect(result.version.tag_name).toBe('1.0.0')
+    expect(result.version.tag_name).toBe('latest')
   })
 
   it('should fall back to rpm when dnf is not available', async () => {
@@ -137,7 +137,7 @@ describe('install-rpm', () => {
       expect.arrayContaining(['dnf'])
     )
     expect(result.elidePath).toBe('/usr/bin/elide')
-    expect(result.version.tag_name).toBe('1.0.0')
+    expect(result.version.tag_name).toBe('latest')
   })
 
   it('should return correct release info', async () => {
@@ -155,7 +155,7 @@ describe('install-rpm', () => {
     expect(result.elidePath).toBe('/usr/bin/elide')
     expect(result.elideBin).toBe('/usr/bin')
     expect(result.elideHome).toBe('/usr/bin')
-    expect(result.version.tag_name).toBe('1.0.0')
+    expect(result.version.tag_name).toBe('1.2.3')
     expect(result.version.userProvided).toBe(true)
   })
 })

__tests__/install-shell.test.ts

@@ -80,7 +80,7 @@ describe('install-shell', () => {
         '--gha'
       ])
       expect(result.elidePath).toBe('/usr/local/bin/elide')
-      expect(result.version.tag_name).toBe('1.0.0')
+      expect(result.version.tag_name).toBe('latest')
     })
 
     it('should pass --version when a specific version is requested', async () => {
@@ -137,7 +137,7 @@ describe('install-shell', () => {
         '-Gha'
       ])
       expect(result.elidePath).toBe('/usr/local/bin/elide')
-      expect(result.version.tag_name).toBe('1.0.0')
+      expect(result.version.tag_name).toBe('latest')
     })
 
     it('should pass -Version when a specific version is requested', async () => {

__tests__/main.test.ts

@@ -85,6 +85,7 @@ mock.module('../src/telemetry', () => ({
 }))
 
 const main = await import('../src/main')
+const { versionMatchesTag } = main
 const { default: buildOptions, OptionName } = await import('../src/options')
 const { ElideArch, ElideOS } = await import('../src/releases')
 const { ActionOutputName } = await import('../src/main')
@@ -105,6 +106,53 @@ const setupMocks = () => {
   setFailedMock.mockImplementation(() => {})
 }
 
+describe('versionMatchesTag', () => {
+  it('exact match', () => {
+    expect(versionMatchesTag('1.0.0', '1.0.0')).toBe(true)
+  })
+
+  it('exact match with prerelease tag', () => {
+    expect(versionMatchesTag('1.0.0-beta10', '1.0.0-beta10')).toBe(true)
+  })
+
+  it('exact match with build-metadata tag', () => {
+    expect(versionMatchesTag('1.4.0+20260707', '1.4.0+20260707')).toBe(true)
+  })
+
+  it('commit-hash suffix on plain semver tag', () => {
+    expect(versionMatchesTag('1.0.0.6f7ffa7', '1.0.0')).toBe(true)
+  })
+
+  it('commit-hash suffix on prerelease tag', () => {
+    expect(versionMatchesTag('1.0.0-beta10.6f7ffa7', '1.0.0-beta10')).toBe(true)
+  })
+
+  it('commit-hash suffix on build-metadata tag', () => {
+    expect(versionMatchesTag('1.4.0+20260707.6f7ffa7', '1.4.0+20260707')).toBe(
+      true
+    )
+  })
+
+  it('different version — no match', () => {
+    expect(versionMatchesTag('9.9.9', '1.0.0')).toBe(false)
+  })
+
+  it('binary ahead of requested prerelease — no match', () => {
+    expect(versionMatchesTag('1.0.0', '1.0.0-beta10')).toBe(false)
+  })
+
+  it('tag is not a prefix without dot separator — no match', () => {
+    // "1.0.01" must not match tag "1.0.0" (no dot between them)
+    expect(versionMatchesTag('1.0.01', '1.0.0')).toBe(false)
+  })
+
+  it('binary build date does not match tag build date — no match', () => {
+    expect(versionMatchesTag('1.4.0+20260708.6f7ffa7', '1.4.0+20260707')).toBe(
+      false
+    )
+  })
+})
+
 describe('action', () => {
   beforeEach(() => {
     execMock.mockClear()
@@ -436,7 +484,7 @@ describe('action', () => {
   it('should warn on version mismatch', async () => {
     setupMocks()
     obtainVersionMock.mockResolvedValueOnce('1.0.0').mockResolvedValue('9.9.9')
-    await main.run({ force: true, installer: 'shell' })
+    await main.run({ force: true, installer: 'shell', version: '1.0.0' })
     expect(warningMock).toHaveBeenCalledWith(
       expect.stringContaining('Elide version mismatch'),
       expect.objectContaining({ title: 'Version Mismatch' })

__tests__/releases-download.test.ts

@@ -56,8 +56,12 @@ mock.module('../src/command', () => ({
   elideInfo: jest.fn()
 }))
 
-const { downloadRelease, resolveLatestVersion, toSemverCacheKey } =
-  await import('../src/releases')
+const {
+  downloadRelease,
+  resolveLatestVersion,
+  resolveVersionByTag,
+  toSemverCacheKey
+} = await import('../src/releases')
 const { default: buildOptions } = await import('../src/options')
 
 describe('resolveLatestVersion', () => {
@@ -115,6 +119,91 @@ describe('resolveLatestVersion', () => {
   })
 })
 
+// resolveVersionByTag's retry loop sleeps for real between attempts; run the
+// callback with setTimeout firing immediately so retry tests don't pay that
+// delay in wall-clock time.
+async function withInstantRetryDelay<T>(fn: () => Promise<T>): Promise<T> {
+  const realSetTimeout = globalThis.setTimeout
+  globalThis.setTimeout = ((cb: () => void) => {
+    cb()
+    return 0 as unknown as ReturnType<typeof setTimeout>
+  }) as typeof setTimeout
+  try {
+    return await fn()
+  } finally {
+    globalThis.setTimeout = realSetTimeout
+  }
+}
+
+describe('resolveVersionByTag', () => {
+  beforeEach(() => {
+    requestMock.mockClear()
+    getOctokitMock.mockClear()
+    warningMock.mockClear()
+    debugMock.mockClear()
+  })
+
+  it('should resolve a tag with matching assets', async () => {
+    requestMock.mockResolvedValue({
+      data: {
+        tag_name: '1.4.1+20260716',
+        name: 'Elide 1.4.1+20260716',
+        assets: [
+          {
+            name: 'elide.linux-amd64.tgz',
+            browser_download_url:
+              'https://github.com/elide-dev/elide/releases/download/1.4.1%2B20260716/elide.linux-amd64.tgz'
+          }
+        ]
+      }
+    })
+    const result = await resolveVersionByTag('1.4.1+20260716', 'ghp_test')
+    expect(result.tag_name).toBe('1.4.1+20260716')
+    expect(result.userProvided).toBe(true)
+    expect(result.assets).toHaveLength(1)
+    expect(result.assets?.[0].name).toBe('elide.linux-amd64.tgz')
+  })
+
+  it('should warn when no token is provided', async () => {
+    requestMock.mockResolvedValue({ data: { tag_name: 'x', assets: [] } })
+    await resolveVersionByTag('nightly-20260328')
+    expect(warningMock).toHaveBeenCalledWith(
+      expect.stringContaining('No GitHub token provided')
+    )
+  })
+
+  it('should retry on transient failure and succeed', async () => {
+    requestMock
+      .mockRejectedValueOnce(new Error('rate limit exceeded'))
+      .mockResolvedValueOnce({
+        data: { tag_name: 'nightly-20260328', assets: [] }
+      })
+    const result = await withInstantRetryDelay(() =>
+      resolveVersionByTag('nightly-20260328')
+    )
+    expect(result.tag_name).toBe('nightly-20260328')
+    expect(requestMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('should fall back immediately on a definitive not-found, without throwing', async () => {
+    requestMock.mockRejectedValue(
+      Object.assign(new Error('Not Found'), { status: 404 })
+    )
+    const result = await resolveVersionByTag('1.4.1+20260716')
+    expect(result).toEqual({ tag_name: '1.4.1+20260716', userProvided: true })
+    expect(requestMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('should fall back after exhausting retries on transient errors, without throwing', async () => {
+    requestMock.mockRejectedValue(new Error('quota exhausted'))
+    const result = await withInstantRetryDelay(() =>
+      resolveVersionByTag('1.4.1+20260716')
+    )
+    expect(result).toEqual({ tag_name: '1.4.1+20260716', userProvided: true })
+    expect(requestMock).toHaveBeenCalledTimes(3)
+  })
+})
+
 describe('toSemverCacheKey', () => {
   it('should pass through valid semver', () => {
     expect(toSemverCacheKey('1.0.0')).toBe('1.0.0')
@@ -190,6 +279,109 @@ describe('downloadRelease', () => {
     expect(result.version.userProvided).toBe(true)
   })
 
+  it('should resolve a build-metadata pin via GitHub API and prefer the matching asset URL', async () => {
+    requestMock.mockResolvedValue({
+      data: {
+        tag_name: '1.4.1+20260716',
+        name: 'Elide 1.4.1+20260716',
+        assets: [
+          {
+            name: 'elide.linux-amd64.tgz',
+            browser_download_url:
+              'https://github.com/elide-dev/elide/releases/download/tag/elide.linux-amd64.tgz'
+          }
+        ]
+      }
+    })
+    const options = buildOptions({
+      os: 'linux',
+      arch: 'amd64',
+      version: '1.4.1+20260716'
+    })
+    const result = await downloadRelease(options)
+    expect(requestMock).toHaveBeenCalled()
+    expect(downloadToolMock).toHaveBeenCalledWith(
+      'https://github.com/elide-dev/elide/releases/download/tag/elide.linux-amd64.tgz'
+    )
+    expect(result.version.tag_name).toBe('1.4.1+20260716')
+  })
+
+  it('should prefer a tgz release asset even when xz is available locally but no txz asset was published', async () => {
+    whichMock.mockResolvedValue('/usr/bin/xz')
+    requestMock.mockResolvedValue({
+      data: {
+        tag_name: '1.4.1+20260716',
+        name: 'Elide 1.4.1+20260716',
+        assets: [
+          {
+            name: 'elide.linux-amd64.tgz',
+            browser_download_url:
+              'https://github.com/elide-dev/elide/releases/download/tag/elide.linux-amd64.tgz'
+          }
+        ]
+      }
+    })
+    const options = buildOptions({
+      os: 'linux',
+      arch: 'amd64',
+      version: '1.4.1+20260716'
+    })
+    const result = await downloadRelease(options)
+    expect(downloadToolMock).toHaveBeenCalledWith(
+      'https://github.com/elide-dev/elide/releases/download/tag/elide.linux-amd64.tgz'
+    )
+    expect(result.version.tag_name).toBe('1.4.1+20260716')
+  })
+
+  it('should NOT call the GitHub API for a build-metadata pin on a warm cache hit', async () => {
+    findMock.mockReturnValue('/cache/tools/elide/1.4.1-build.20260716/amd64')
+    const options = buildOptions({
+      os: 'linux',
+      arch: 'amd64',
+      version: '1.4.1+20260716'
+    })
+    const result = await downloadRelease(options)
+    expect(requestMock).not.toHaveBeenCalled()
+    expect(downloadToolMock).not.toHaveBeenCalled()
+    expect(result.cached).toBe(true)
+  })
+
+  it('should NOT call the GitHub API for a "+"-containing pin that is not semver-shaped', async () => {
+    const options = buildOptions({
+      os: 'linux',
+      arch: 'amd64',
+      version: 'myfork+patch1'
+    })
+    await downloadRelease(options)
+    expect(requestMock).not.toHaveBeenCalled()
+  })
+
+  it('should fall back to the CDN URL when the build-metadata tag lookup fails', async () => {
+    requestMock.mockRejectedValue(
+      Object.assign(new Error('Not Found'), { status: 404 })
+    )
+    const options = buildOptions({
+      os: 'linux',
+      arch: 'amd64',
+      version: '1.4.1+20260716'
+    })
+    const result = await downloadRelease(options)
+    expect(downloadToolMock).toHaveBeenCalledWith(
+      expect.stringContaining('elide.zip/artifacts')
+    )
+    expect(result.version.tag_name).toBe('1.4.1+20260716')
+  })
+
+  it('should NOT call the GitHub API for a plain semver pin (scoping regression guard)', async () => {
+    const options = buildOptions({
+      os: 'linux',
+      arch: 'amd64',
+      version: '1.2.3'
+    })
+    await downloadRelease(options)
+    expect(requestMock).not.toHaveBeenCalled()
+  })
+
   it('should use a cached copy when available', async () => {
     findMock.mockReturnValue('/cached/elide')
     const options = buildOptions({