free-coding-models 0.5.86 → 0.5.87

package/src/core/model-merger.js

@@ -160,6 +160,10 @@ export async function overlayModelsDevMetadata(mergedModels, opts = {}) {
       }
     }
     if (!bestMatch && m.slug) bestMatch = lookup(m.slug, m.label, index)
+    // 📖 Skip substring matches entirely: a label-only match can bind the WRONG
+    // 📖 catalog model and overwrite the curated ctx window with its value
+    // 📖 (detectDrift ignores substring matches for the same reason).
+    if (bestMatch && bestMatch.matchKind === 'substring') bestMatch = null
     if (!bestMatch) {
       if (opts.mutate) {
         Object.assign(m, { modelsDevMeta: null, metaSource: 'sources.js' })

package/src/core/models-drift.js

@@ -131,8 +131,10 @@ export function detectDrift(models, catalog, opts = {}) {
   for (const entry of models) {
     // 📖 Accept both tuple form and object form
     let modelId, label, ctx, reasoning, vision, thinking, maxTokens
+    let isTupleForm = false
     if (Array.isArray(entry)) {
       [modelId, label, , , ctx] = entry
+      isTupleForm = true
       // 📖 The 6th+ elements of the sources.js tuple are providerKey + metadata;
       // 📖 for drift we only need the first 5.
     } else if (entry && typeof entry === 'object') {
@@ -162,6 +164,13 @@ export function detectDrift(models, catalog, opts = {}) {
         matchKind,
       })
     }
+
+    // 📖 Tuple-form entries carry no capability flags or maxTokens (arity 5), so
+    // 📖 flagMatch(undefined, true) used to report a bogus "add" for every capable
+    // 📖 model and bury the real ctx drift under noise. Only object-form entries
+    // 📖 (which can actually hold these fields) are compared.
+    if (isTupleForm) continue
+
     // maxTokens
     const maxCmp = numMatch(maxTokens, norm.maxOutputTokens)
     if (maxCmp.status === 'drift' || maxCmp.status === 'add') {

package/src/core/opencode-config.js

@@ -8,37 +8,89 @@
  *   📖 This module deliberately stays tiny so OpenCode launch code is not
  *   📖 coupled to old bridge-specific sync behavior anymore.
  *
+ *   📖 Data-loss guard: an existing opencode.json that fails to parse returns
+ *   📖 null from `loadOpenCodeConfig`, and `saveOpenCodeConfig` refuses to write
+ *   📖 over an unreadable file. Saving from the empty `{}` base would otherwise
+ *   📖 silently replace the user's whole config with a near-empty one.
+ *
  * @functions
- *   → `loadOpenCodeConfig` — read `~/.config/opencode/opencode.json` safely
- *   → `saveOpenCodeConfig` — write `opencode.json` with a simple backup
+ *   → `loadOpenCodeConfig` - read `~/.config/opencode/opencode.json` safely (null when unreadable)
+ *   → `saveOpenCodeConfig` - write `opencode.json` atomically with a simple backup
  *   → `restoreOpenCodeBackup` — restore the last `.bak` copy if needed
  *
  * @exports loadOpenCodeConfig, saveOpenCodeConfig, restoreOpenCodeBackup
  */
 
-import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs'
+import { readFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { atomicWriteJson } from './shared-helpers.js'
 
 const OPENCODE_CONFIG_DIR = join(homedir(), '.config', 'opencode')
 const OPENCODE_CONFIG_PATH = join(OPENCODE_CONFIG_DIR, 'opencode.json')
 const OPENCODE_BACKUP_PATH = join(OPENCODE_CONFIG_DIR, 'opencode.json.bak')
 
+const UNREADABLE_CONFIG_HINT = `  ⚠ ${OPENCODE_CONFIG_PATH} contains invalid JSON and was NOT modified. Fix or remove the file, then retry.`
+
+/**
+ * 📖 True when the file exists, is non-empty, and does not parse as JSON.
+ * 📖 Missing and empty files are considered readable (nothing to lose).
+ */
+function isExistingFileUnreadable(configPath) {
+  if (!existsSync(configPath)) return false
+  try {
+    const raw = readFileSync(configPath, 'utf8')
+    if (!raw.trim()) return false
+    JSON.parse(raw)
+    return false
+  } catch {
+    return true
+  }
+}
+
 export function loadOpenCodeConfig() {
   try {
     if (existsSync(OPENCODE_CONFIG_PATH)) {
-      return JSON.parse(readFileSync(OPENCODE_CONFIG_PATH, 'utf8'))
+      const raw = readFileSync(OPENCODE_CONFIG_PATH, 'utf8')
+      // 📖 Missing file and empty file behave as before: fresh empty base.
+      if (!raw.trim()) return {}
+      try {
+        return JSON.parse(raw)
+      } catch {
+        // 📖 Existing non-empty file with broken JSON: signal "unreadable" so
+        // 📖 callers never build a save on an empty base and wipe the file.
+        return null
+      }
     }
   } catch {}
   return {}
 }
 
+/**
+ * 📖 Save opencode.json atomically (tmp + rename) with a one-shot backup.
+ * 📖 Returns false and aborts (with a clear message) instead of overwriting
+ * 📖 when the config is null or the on-disk file is unreadable.
+ * @param {object|null} config
+ * @returns {boolean} true when written
+ */
 export function saveOpenCodeConfig(config) {
+  if (config === null || config === undefined) {
+    console.error(UNREADABLE_CONFIG_HINT)
+    return false
+  }
+  // 📖 Belt-and-suspenders for callers that normalized null to {}: never let a
+  // 📖 stale in-memory copy clobber a file we cannot read.
+  if (isExistingFileUnreadable(OPENCODE_CONFIG_PATH)) {
+    console.error(UNREADABLE_CONFIG_HINT)
+    return false
+  }
   mkdirSync(OPENCODE_CONFIG_DIR, { recursive: true })
   if (existsSync(OPENCODE_CONFIG_PATH)) {
     copyFileSync(OPENCODE_CONFIG_PATH, OPENCODE_BACKUP_PATH)
   }
-  writeFileSync(OPENCODE_CONFIG_PATH, JSON.stringify(config, null, 2) + '\n')
+  // 📖 Atomic write: a crash mid-write must never truncate the shared config.
+  atomicWriteJson(OPENCODE_CONFIG_PATH, config, 0o600)
+  return true
 }
 
 export function restoreOpenCodeBackup() {

package/src/core/opencode.js

@@ -14,7 +14,7 @@
  *   - Auto-pick tmux port for OpenCode sub-agents
  *
  *   → Functions:
- *   - `setOpenCodeModelData` — Keep shared merged model references available
+ *   - `setOpenCodeModelData` - No-op kept for call-site stability (dead refs removed)
  *   - `startOpenCode` — Launch OpenCode CLI with selected model
  *   - `startOpenCodeDesktop` — Set model and open Desktop app
  *
@@ -41,15 +41,10 @@ const OPENCODE_CONFIG = join(homedir(), '.config', 'opencode', 'opencode.json')
 const OPENCODE_PORT_RANGE_START = 4096
 const OPENCODE_PORT_RANGE_END = 5096
 
-// 📖 Keep merged model references available for future OpenCode-related features.
-let mergedModelsRef = []
-let mergedModelByLabelRef = new Map()
-
-// 📖 setOpenCodeModelData: Provide mergedModels + mergedModelByLabel to this module.
-export function setOpenCodeModelData(mergedModels, mergedModelByLabel) {
-  mergedModelsRef = Array.isArray(mergedModels) ? mergedModels : []
-  mergedModelByLabelRef = mergedModelByLabel instanceof Map ? mergedModelByLabel : new Map()
-}
+// 📖 setOpenCodeModelData: kept as a stable no-op export. The merged model refs it
+// 📖 used to store were written but never read anywhere (verified by grep), so the
+// 📖 dead module state was removed; src/tui/app.js still calls this on startup.
+export function setOpenCodeModelData() {}
 
 // 📖 isTcpPortAvailable: checks if a local TCP port is free for OpenCode.
 // 📖 Used to avoid tmux sub-agent port conflicts when multiple projects run in parallel.
@@ -147,7 +142,19 @@ async function createZaiProxy(apiKey) {
       res.writeHead(proxyRes.statusCode, proxyRes.headers)
       proxyRes.pipe(res)
     })
-    proxyReq.on('error', () => { res.writeHead(502); res.end() })
+    proxyReq.on('error', () => {
+      // 📖 Headers may already be flushed to the client mid-stream; writeHead after
+      // 📖 that throws ERR_HTTP_HEADERS_SENT and masks the real proxy error.
+      if (!res.headersSent) res.writeHead(502)
+      res.end()
+    })
+    // 📖 Hang guard: an upstream that never responds used to stall the client
+    // 📖 forever. Destroy the socket and answer 502 when headers are not sent yet.
+    proxyReq.setTimeout(15000, () => {
+      proxyReq.destroy(new Error('ZAI proxy upstream timeout'))
+      if (!res.headersSent) res.writeHead(502)
+      res.end()
+    })
     req.pipe(proxyReq)
   })
   await new Promise(r => server.listen(0, '127.0.0.1', r))
@@ -196,7 +203,9 @@ async function spawnOpenCode(args, providerKey, fcmConfig, existingZaiProxy = nu
   const { spawn } = await import('child_process')
   const child = spawn(resolveToolBinaryPath('opencode') || 'opencode', finalArgs, {
     stdio: 'inherit',
-    shell: true,
+    // 📖 Windows keeps a shell because npm-installed CLIs resolve to .cmd shims;
+    // 📖 everywhere else the resolved absolute binary path is spawned directly.
+    shell: isWindows,
     detached: false,
     env: childEnv
   })
@@ -207,7 +216,7 @@ async function spawnOpenCode(args, providerKey, fcmConfig, existingZaiProxy = nu
       // 📖 ZAI cleanup: remove the ephemeral proxy provider from opencode.json
       if (providerKey === 'zai') {
         try {
-          const cfg = loadOpenCodeConfig()
+          const cfg = loadOpenCodeConfig() || {}
           if (cfg.provider?.zai) delete cfg.provider.zai
           if (typeof cfg.model === 'string' && cfg.model.startsWith('zai/')) delete cfg.model
           saveOpenCodeConfig(cfg)
@@ -236,7 +245,7 @@ export async function startOpenCode(model, fcmConfig) {
   const modelRef = `${providerKey}/${ocModelId}`
 
   if (providerKey === 'nvidia') {
-    const config = loadOpenCodeConfig()
+    const config = loadOpenCodeConfig() || {}
     const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
     if (existsSync(getOpenCodeConfigPath())) {
@@ -271,7 +280,7 @@ export async function startOpenCode(model, fcmConfig) {
 
     saveOpenCodeConfig(config)
 
-    const savedConfig = loadOpenCodeConfig()
+    const savedConfig = loadOpenCodeConfig() || {}
     console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
     console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
     console.log()
@@ -312,7 +321,7 @@ export async function startOpenCode(model, fcmConfig) {
     console.log(chalk.dim(`  Model: ${modelRef}`))
     console.log()
 
-    const config = loadOpenCodeConfig()
+    const config = loadOpenCodeConfig() || {}
     const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
     if (existsSync(getOpenCodeConfigPath())) {
@@ -335,7 +344,7 @@ export async function startOpenCode(model, fcmConfig) {
 
     saveOpenCodeConfig(config)
 
-    const savedConfig = loadOpenCodeConfig()
+    const savedConfig = loadOpenCodeConfig() || {}
     console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
     console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
     console.log()
@@ -361,7 +370,7 @@ export async function startOpenCode(model, fcmConfig) {
     console.log(chalk.dim(`  Model: ${zenModelRef}`))
     console.log()
 
-    const config = loadOpenCodeConfig()
+    const config = loadOpenCodeConfig() || {}
     const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
     if (existsSync(getOpenCodeConfigPath())) {
@@ -372,7 +381,7 @@ export async function startOpenCode(model, fcmConfig) {
     config.model = zenModelRef
     saveOpenCodeConfig(config)
 
-    const savedConfig = loadOpenCodeConfig()
+    const savedConfig = loadOpenCodeConfig() || {}
     console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
     console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
     console.log()
@@ -392,7 +401,7 @@ export async function startOpenCode(model, fcmConfig) {
   console.log(chalk.dim(`  Model: ${modelRef}`))
   console.log()
 
-  const config = loadOpenCodeConfig()
+  const config = loadOpenCodeConfig() || {}
   const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
   if (existsSync(getOpenCodeConfigPath())) {
@@ -559,7 +568,7 @@ export async function startOpenCode(model, fcmConfig) {
   config.model = modelRef
   saveOpenCodeConfig(config)
 
-  const savedConfig = loadOpenCodeConfig()
+  const savedConfig = loadOpenCodeConfig() || {}
   console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
   console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
   console.log()
@@ -587,7 +596,7 @@ export async function startOpenCodeWeb(model, fcmConfig) {
   console.log(chalk.dim(`  Model: ${modelRef}`))
   console.log()
 
-  const config = loadOpenCodeConfig()
+  const config = loadOpenCodeConfig() || {}
   const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
   if (existsSync(getOpenCodeConfigPath())) {
@@ -639,33 +648,50 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
   const ocModelId = getOpenCodeModelId(providerKey, model.modelId)
   const modelRef = `${providerKey}/${ocModelId}`
 
+  const printDesktopLaunchError = () => {
+    console.error(chalk.red('  Could not open OpenCode Desktop'))
+    if (isWindows) {
+      console.error(chalk.dim('    Make sure OpenCode is installed from https://opencode.ai'))
+    } else if (isLinux) {
+      console.error(chalk.dim('    Install via: snap install opencode OR flatpak install ai.opencode.OpenCode'))
+      console.error(chalk.dim('    Or download from https://opencode.ai'))
+    } else {
+      console.error(chalk.dim('    Is it installed at /Applications/OpenCode.app?'))
+    }
+  }
+
   const launchDesktop = async () => {
+    // 📖 Linux: try each launcher directly (shell:false) so modelRef is never
+    // 📖 interpolated into a shell command string. The final candidate opens the
+    // 📖 .desktop entry without a model argument.
+    if (isLinux) {
+      const { execFile } = await import('child_process')
+      const tryExecFile = (cmd, args) => new Promise((resolve) => {
+        execFile(cmd, args, (err) => resolve(!err))
+      })
+      const launched =
+        (await tryExecFile('opencode-desktop', ['--model', modelRef])) ||
+        (await tryExecFile('flatpak', ['run', 'ai.opencode.OpenCode', '--model', modelRef])) ||
+        (await tryExecFile('snap', ['run', 'opencode', '--model', modelRef])) ||
+        (await tryExecFile('xdg-open', ['/usr/share/applications/opencode.desktop']))
+      if (!launched) printDesktopLaunchError()
+      return
+    }
+
     const { exec } = await import('child_process')
     let command
     if (isMac) {
       command = 'open -a OpenCode'
     } else if (isWindows) {
       command = 'start "" "%LOCALAPPDATA%\\Programs\\OpenCode\\OpenCode.exe" 2>nul || start "" "%PROGRAMFILES%\\OpenCode\\OpenCode.exe" 2>nul || start OpenCode'
-    } else if (isLinux) {
-      command = `opencode-desktop --model ${modelRef} 2>/dev/null || flatpak run ai.opencode.OpenCode --model ${modelRef} 2>/dev/null || snap run opencode --model ${modelRef} 2>/dev/null || xdg-open /usr/share/applications/opencode.desktop 2>/dev/null || echo "OpenCode not found"`
     }
     exec(command, (err) => {
-      if (err) {
-        console.error(chalk.red('  Could not open OpenCode Desktop'))
-        if (isWindows) {
-          console.error(chalk.dim('    Make sure OpenCode is installed from https://opencode.ai'))
-        } else if (isLinux) {
-          console.error(chalk.dim('    Install via: snap install opencode OR flatpak install ai.opencode.OpenCode'))
-          console.error(chalk.dim('    Or download from https://opencode.ai'))
-        } else {
-          console.error(chalk.dim('    Is it installed at /Applications/OpenCode.app?'))
-        }
-      }
+      if (err) printDesktopLaunchError()
     })
   }
 
   if (providerKey === 'nvidia') {
-    const config = loadOpenCodeConfig()
+    const config = loadOpenCodeConfig() || {}
     const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
     if (existsSync(getOpenCodeConfigPath())) {
@@ -700,7 +726,7 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
 
     saveOpenCodeConfig(config)
 
-    const savedConfig = loadOpenCodeConfig()
+    const savedConfig = loadOpenCodeConfig() || {}
     console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
     console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
     console.log()
@@ -741,7 +767,7 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
     console.log(chalk.dim(`  Model: ${zenModelRef}`))
     console.log()
 
-    const config = loadOpenCodeConfig()
+    const config = loadOpenCodeConfig() || {}
     const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
     if (existsSync(getOpenCodeConfigPath())) {
@@ -752,7 +778,7 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
     config.model = zenModelRef
     saveOpenCodeConfig(config)
 
-    const savedConfig = loadOpenCodeConfig()
+    const savedConfig = loadOpenCodeConfig() || {}
     console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
     console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
     console.log()
@@ -774,7 +800,7 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
   console.log(chalk.dim(`  Model: ${modelRef}`))
   console.log()
 
-  const config = loadOpenCodeConfig()
+  const config = loadOpenCodeConfig() || {}
   const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
 
   if (existsSync(getOpenCodeConfigPath())) {
@@ -941,7 +967,7 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
   config.model = modelRef
   saveOpenCodeConfig(config)
 
-  const savedConfig = loadOpenCodeConfig()
+  const savedConfig = loadOpenCodeConfig() || {}
   console.log(chalk.dim(`  Config saved to: ${getOpenCodeConfigPath()}`))
   console.log(chalk.dim(`  Default model in config: ${savedConfig.model || 'NOT SET'}`))
   console.log()

package/src/core/playground.js

@@ -190,6 +190,11 @@ export async function playgroundSubmit(state, deps = {}) {
   const url = `http://127.0.0.1:${port}/v1/chat/completions`
   const fetchFn = deps.fetchFn || globalThis.fetch
 
+  // 📖 Non-streaming responses have no per-chunk timer, so give the whole
+  // 📖 request the same 90s ceiling. The streaming branch switches to its own
+  // 📖 per-chunk timer inside readSseStream.
+  let requestTimer = setTimeout(() => controller.abort(), STREAM_TIMEOUT_MS)
+
   try {
     const resp = await fetchFn(url, {
       method: 'POST',
@@ -205,6 +210,7 @@ export async function playgroundSubmit(state, deps = {}) {
       return
     }
     if (PLAYGROUND_OVERLAY_STATE.streamOn) {
+      clearTimeout(requestTimer)
       await readSseStream(resp, fetchFn, controller)
     } else {
       const json = await resp.json().catch(() => null)
@@ -231,6 +237,7 @@ export async function playgroundSubmit(state, deps = {}) {
       finalizeAssistantMeta({ error: PLAYGROUND_OVERLAY_STATE.lastError, aborted: true })
     }
   } finally {
+    clearTimeout(requestTimer)
     PLAYGROUND_OVERLAY_STATE.busy = false
     PLAYGROUND_OVERLAY_STATE.abortController = null
     PLAYGROUND_OVERLAY_STATE.statusMessage = null

package/src/core/probe-cache.js

@@ -104,6 +104,14 @@ const CACHE_DIRNAME = 'free-coding-models'
 let _cache = null
 let _cacheLoadedFrom = null  // path we last loaded from (for write-back)
 
+/**
+ * 📖 Composite `provider::model` keys pruned this session. flushCache() re-reads
+ * 📖 the disk file before writing, and the read-merge-write pass would otherwise
+ * 📖 resurrect exactly the entries pruneStaleEntries() just deleted (the disk file
+ * 📖 still contains them until our write lands).
+ */
+const _sessionPrunedKeys = new Set()
+
 // ─── Path resolution ──────────────────────────────────────────────────────────
 
 /**
@@ -180,16 +188,24 @@ export function loadCache({ path: cachePath } = {}) {
  * 📖 from incoming do NOT delete fields from base. Used by flushCache to merge
  * 📖 our in-memory mirror with whatever the on-disk file now contains (covers
  * 📖 the daemon + CLI running concurrently case).
+ *
+ * 📖 `excludeKeys` (optional Set of `provider::model`) drops matching base
+ * 📖 entries: keys pruned this session must stay pruned instead of coming back
+ * 📖 from the stale disk snapshot.
  */
-function mergeCache(base, incoming) {
+function mergeCache(base, incoming, excludeKeys = null) {
   if (!base || typeof base !== 'object') return incoming
   if (!incoming || typeof incoming !== 'object') return base
   const out = { ...incoming, providers: { ...(incoming.providers || {}) } }
   for (const [providerKey, providerBucket] of Object.entries(base.providers || {})) {
     const incomingBucket = out.providers[providerKey] || { models: {} }
-    out.providers[providerKey] = {
-      models: { ...(providerBucket?.models || {}), ...(incomingBucket.models || {}) },
+    const mergedModels = { ...(providerBucket?.models || {}), ...(incomingBucket.models || {}) }
+    if (excludeKeys && excludeKeys.size > 0) {
+      for (const modelId of Object.keys(mergedModels)) {
+        if (excludeKeys.has(`${providerKey}::${modelId}`)) delete mergedModels[modelId]
+      }
     }
+    out.providers[providerKey] = { models: mergedModels }
   }
   return out
 }
@@ -220,12 +236,15 @@ export function flushCache({ path: cachePath, cache } = {}) {
     onDisk = null
   }
 
-  const merged = onDisk ? mergeCache(onDisk, localData) : localData
+  const merged = onDisk ? mergeCache(onDisk, localData, _sessionPrunedKeys) : localData
 
   try {
     atomicWriteJson(target, merged, 0o600)
     _cacheLoadedFrom = target
     _cache = merged
+    // 📖 Deletions are now persisted: clear the set so entries re-added later by
+    // 📖 another process (e.g. the model returned to the catalog) still merge in.
+    _sessionPrunedKeys.clear()
     return true
   } catch {
     return false
@@ -244,6 +263,8 @@ export function clearCache({ path: cachePath } = {}) {
   const target = cachePath ?? getProbeCachePath()
   _cache = null
   _cacheLoadedFrom = null
+  // 📖 The file is gone, so tracked deletions have nothing left to override.
+  _sessionPrunedKeys.clear()
   try {
     fs.unlinkSync(target)
     return true
@@ -406,6 +427,11 @@ export function recordProbeResults(providerKey, results, opts = {}) {
         probeVersion: CURRENT_PROBE_VERSION,
         consecutiveFailures,
       }
+      // 📖 A live re-probe of a pruned model means it is catalogued again: stop
+      // 📖 excluding it from disk merges.
+      if (!opts || !Object.prototype.hasOwnProperty.call(opts, 'cache')) {
+        _sessionPrunedKeys.delete(`${providerKey}::${r.modelId}`)
+      }
       written++
     } catch {
       dropped++
@@ -553,6 +579,11 @@ export function pruneStaleEntries(providerKey, liveModelIds, opts = {}) {
   for (const id of Object.keys(bucket)) {
     if (!live.has(id)) {
       delete bucket[id]
+      // 📖 Remember the deletion so flushCache's read-merge-write does not
+      // 📖 resurrect this entry from the still-stale disk file.
+      if (!opts || !Object.prototype.hasOwnProperty.call(opts, 'cache')) {
+        _sessionPrunedKeys.add(`${providerKey}::${id}`)
+      }
       pruned++
     }
   }

package/src/core/provider-key-tester.js

@@ -305,7 +305,11 @@ export async function runProviderKeyTest(apiKey, providerKey, source, options =
         headers['HTTP-Referer'] = 'https://github.com/vava-nessa/free-coding-models'
         headers['X-Title'] = 'free-coding-models'
       }
-      const modelsResp = await fetch(modelsUrl, { headers })
+      const modelsResp = await fetch(modelsUrl, {
+        headers,
+        // 📖 Same 8s ceiling as the fast-path probes so discovery can never hang.
+        signal: AbortSignal.timeout(8000),
+      })
       if (modelsResp.ok) {
         const data = await modelsResp.json()
         discoveredModelIds.push(...parseProviderModelIds(data))
@@ -316,7 +320,11 @@ export async function runProviderKeyTest(apiKey, providerKey, source, options =
         discoveryNote = `Live model discovery returned HTTP ${modelsResp.status}; falling back to the repo catalog.`
       }
     } catch (err) {
-      discoveryNote = `Live model discovery failed (${err?.name || 'error'}); falling back to the repo catalog.`
+      // 📖 AbortSignal.timeout rejects with TimeoutError; treat it like the fast-path timeout.
+      const timedOut = err?.name === 'TimeoutError' || err?.name === 'AbortError'
+      discoveryNote = timedOut
+        ? 'Live model discovery timed out; falling back to the repo catalog.'
+        : `Live model discovery failed (${err?.name || 'error'}); falling back to the repo catalog.`
     }
   }
 

package/src/core/provider-metadata.js

@@ -67,6 +67,16 @@ export const ENV_VAR_NAMES = {
   requesty:   'REQUESTY_API_KEY',
   orcarouter: 'ORCAROUTER_API_KEY',
   'vercel-gateway': 'VERCEL_AI_GATEWAY_API_KEY',
+  // 📖 Providers whose OpenCode/Kilo config writers reference {env:VAR} - names
+  // 📖 must match those tables exactly (see opencode.js / kilo.js).
+  huggingface: 'HUGGINGFACE_API_KEY',
+  deepinfra:  'DEEPINFRA_API_KEY',
+  fireworks:  'FIREWORKS_API_KEY',
+  together:   'TOGETHER_API_KEY',
+  hyperbolic: 'HYPERBOLIC_API_KEY',
+  perplexity: 'PERPLEXITY_API_KEY',
+  chutes:     'CHUTES_API_KEY',
+  iflow:      'IFLOW_API_KEY',
 }
 
 // 📖 OPENCODE_MODEL_MAP: sparse table of model IDs that differ between sources.js and OpenCode's

package/src/core/provider-quota-fetchers.js

@@ -134,10 +134,11 @@ export function parseSiliconFlowResponse(responseData) {
  * Create an in-memory cache entry.
  * @param {number|null} value
  * @param {number} expiresAt - Date.now() timestamp
- * @returns {{ value: number|null, expiresAt: number }}
+ * @param {number} [resolvedAt=Date.now()] - when the value was actually fetched
+ * @returns {{ value: number|null, expiresAt: number, resolvedAt: number }}
  */
-function makeCacheEntry(value, expiresAt) {
-  return { value, expiresAt }
+function makeCacheEntry(value, expiresAt, resolvedAt = Date.now()) {
+  return { value, expiresAt, resolvedAt }
 }
 
 // ─── Endpoint definitions ─────────────────────────────────────────────────────
@@ -320,7 +321,8 @@ export async function fetchProviderQuota(providerKey, apiKey, options = {}) {
   const pendingPromise = doFetch()
     .then((value) => {
       const finalValue = (typeof value === 'number' && Number.isFinite(value)) ? value : null
-      _defaultCache.set(cacheKey, makeCacheEntry(finalValue, Date.now() + cacheTtlMs))
+      const resolvedAt = Date.now()
+      _defaultCache.set(cacheKey, makeCacheEntry(finalValue, resolvedAt + cacheTtlMs, resolvedAt))
       return finalValue
     })
     .catch(() => {
@@ -483,12 +485,17 @@ function getActiveSnapshot(providerKey, now = Date.now()) {
     if (typeof entry.expiresAt !== 'number' || entry.expiresAt <= now) continue
     const value = entry.value
     if (typeof value !== 'number' || !Number.isFinite(value)) continue
+    // 📖 lastUpdated must be when the value was actually fetched, not "now": a
+    // 📖 TTL-cached value can be up to 60s old, and stamping it with now made it
+    // 📖 always beat real passive header snapshots in getQuota's freshest-wins
+    // 📖 pick while fabricating a fresh remaining/limit.
+    const resolvedAt = typeof entry.resolvedAt === 'number'
+      ? entry.resolvedAt
+      : entry.expiresAt - DEFAULT_CACHE_TTL_MS
     return makeSnapshot(
       { remaining: value, limit: 100, percent: value, windowType: 'unknown', source: 'active_fetcher' },
       'endpoint',
-      // 📖 active fetcher stores wall-clock ms at fetch time; expose it so
-      // 📖 getQuota's freshest-wins logic works on real timestamps.
-      now,
+      resolvedAt,
     )
   }
   return null