fix(overlay): collapse empty cache to unknown availability status (#378)

When the API call fails (timeout, throw, or error envelope) and the local
`models.json` cache is readable but produces a zero-size set,
`readFallbackCache` was returning `{ status: 'cache', models: <empty Set> }`.
The downstream gate `availability.status !== 'unknown'` admitted this,
`availabilitySet` became the empty Set, and `resolveSourceModel` fell
through to the 'last-resort: first provider's first model' path —
pinning bundled agents to a provider the user cannot call.

Symmetric with the empty-API collapse from PR #372: both branches in
`readFallbackCache` now check `result.size > 0` before returning
`{ status: 'cache', ... }`, so an empty cache funnels through
`emptyAvailability()` (status: 'unknown') just like the empty-API case.
Downstream consumers stay on a single gate rule rather than
`status !== 'unknown' && models.size > 0` everywhere.

Three regression tests cover the three empty-cache shapes: schema-valid
empty object, providers-with-empty-models, and OPENCODE_MODELS_URL-derived
empty cache. The DiscoveryStatus JSDoc for 'cache' is updated to reflect
the non-empty contract.

Closes #373

Author: marcusrbrown

src/lib/model-availability.ts

@@ -35,10 +35,10 @@ export interface OpencodeClientLike {
  *   operational consequence is identical and downstream consumers should treat
  *   both cases the same way.
  * - `cache`: The API call failed (error envelope, thrown, or timed out) and
- *   the local `models.json` cache was readable. `models` reflects whatever
- *   OpenCode last wrote to disk. The cache may itself be empty; callers that
- *   need to distinguish "cached empty" from "cached with content" should
- *   inspect `models.size`.
+ *   the local `models.json` cache was readable AND non-empty. `models`
+ *   reflects whatever OpenCode last wrote to disk. A cache that loads
+ *   successfully but produces a zero-size set collapses to `'unknown'` for
+ *   the same operational reason an empty API response does.
  * - `unknown`: Either both the API call and the cache fallback failed (cache
  *   missing, unreadable, corrupt, or schema-mismatched), OR the API call
  *   succeeded with zero usable models. Resolution should degrade gracefully —
@@ -183,6 +183,15 @@ function readFallbackCache(): ModelAvailability {
   const cacheDir = resolveCacheDir()
   const openCodeModelsUrl = process.env.OPENCODE_MODELS_URL?.trim()
 
+  // Both branches below check `result.size > 0` before returning
+  // `{ status: 'cache', ... }`. Symmetric with the empty-API collapse in
+  // `getAvailableModels`: a cache file that loads successfully but produces a
+  // zero-size set is operationally identical to no cache at all — we cannot
+  // point bundled agents at any model the user can call. Funneling the empty
+  // case through `emptyAvailability()` keeps the downstream gate
+  // `availability.status !== 'unknown'` a single rule for every consumer
+  // rather than `status !== 'unknown' && models.size > 0`.
+
   // When OPENCODE_MODELS_URL is set, OpenCode writes the cache to
   // `models-<sha1-hex>.json` where the hash is `Hash.fast(url)` — verified
   // against `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/util/hash.ts`.
@@ -195,7 +204,7 @@ function readFallbackCache(): ModelAvailability {
       `models-${fastHash(openCodeModelsUrl)}.json`,
     )
     const urlResult = readModelsFromCache(urlDerivedPath)
-    if (urlResult !== null) {
+    if (urlResult !== null && urlResult.size > 0) {
       return { status: 'cache', models: urlResult }
     }
     // When OPENCODE_MODELS_URL is set, the URL-derived cache file is the
@@ -208,7 +217,7 @@ function readFallbackCache(): ModelAvailability {
 
   const defaultPath = path.join(cacheDir, MODELS_JSON_FILENAME)
   const defaultResult = readModelsFromCache(defaultPath)
-  if (defaultResult !== null) {
+  if (defaultResult !== null && defaultResult.size > 0) {
     return { status: 'cache', models: defaultResult }
   }
 

tests/unit/model-availability.test.ts

@@ -253,6 +253,79 @@ describe('getAvailableModels', () => {
     })
   })
 
+  describe('edge case: empty cache collapses to unknown', () => {
+    // Parallel of `edge case: empty discovery collapses to unknown` for the cache
+    // fallback path. When the API call fails AND the on-disk cache file is present
+    // but produces a zero-size model set (e.g., schema-valid empty object, or
+    // provider entries with `models: {}`), `readFallbackCache` must collapse to
+    // `emptyAvailability()` rather than returning `{ status: 'cache', models: <empty Set> }`.
+    //
+    // Operationally identical to the empty-API case: an empty set on either path
+    // means we cannot pin bundled agents to anything the user can call. The downstream
+    // gate `availability.status !== 'unknown'` admits any non-'unknown' status, so
+    // the collapse must happen at the envelope construction site to keep the gate a
+    // single rule rather than `status !== 'unknown' && models.size > 0` at every consumer.
+
+    test('returns status: unknown when models.json is a schema-valid empty object', async () => {
+      const cacheDir = path.join(testDir, 'cache', 'opencode')
+      fs.mkdirSync(cacheDir, { recursive: true })
+      fs.writeFileSync(path.join(cacheDir, 'models.json'), '{}')
+      process.env.XDG_CACHE_HOME = path.join(testDir, 'cache')
+
+      const client = makeThrowingClient(new Error('ECONNREFUSED'))
+
+      const result = await getAvailableModels(client)
+
+      expect(result.status).toBe('unknown')
+      expect(result.models).toBeInstanceOf(Set)
+      expect(result.models.size).toBe(0)
+    })
+
+    test('returns status: unknown when models.json has providers with empty models records', async () => {
+      // Catches the case where `enabled_providers` populates entries without
+      // auth-driven model lists — schema is valid, `buildSetFromCache` produces
+      // a zero-size set, but `'cache'` would still slip past the gate without
+      // the collapse.
+      const cacheDir = path.join(testDir, 'cache', 'opencode')
+      fs.mkdirSync(cacheDir, { recursive: true })
+      fs.writeFileSync(
+        path.join(cacheDir, 'models.json'),
+        JSON.stringify({
+          anthropic: { models: {} },
+          openai: { models: {} },
+        }),
+      )
+      process.env.XDG_CACHE_HOME = path.join(testDir, 'cache')
+
+      const client = makeThrowingClient(new Error('ECONNREFUSED'))
+
+      const result = await getAvailableModels(client)
+
+      expect(result.status).toBe('unknown')
+      expect(result.models.size).toBe(0)
+    })
+
+    test('returns status: unknown when OPENCODE_MODELS_URL-derived cache exists but is empty', async () => {
+      // OPENCODE_MODELS_URL routes the cache through the URL-derived `models-<hash>.json`
+      // filename and explicitly does NOT fall through to default models.json (trust-domain
+      // boundary). The collapse must still apply on the URL-derived path.
+      const cacheDir = path.join(testDir, 'cache', 'opencode')
+      fs.mkdirSync(cacheDir, { recursive: true })
+      const url = 'https://models.example.com/registry.json'
+      const hashedFilename = `models-${sha1Hex(url)}.json`
+      fs.writeFileSync(path.join(cacheDir, hashedFilename), '{}')
+      process.env.XDG_CACHE_HOME = path.join(testDir, 'cache')
+      process.env.OPENCODE_MODELS_URL = url
+
+      const client = makeThrowingClient(new Error('ECONNREFUSED'))
+
+      const result = await getAvailableModels(client)
+
+      expect(result.status).toBe('unknown')
+      expect(result.models.size).toBe(0)
+    })
+  })
+
   describe('edge case: cache path resolution', () => {
     test('uses XDG_CACHE_HOME when set', async () => {
       const cacheDir = path.join(testDir, 'xdg-cache', 'opencode')