free-coding-models 0.5.89 → 0.5.90

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Find the fastest free coding model in seconds.</strong><br>
-  Live latency, stability and verdicts for 229 models from 24 free AI providers, then install the one you pick straight into your favorite coding tool.<br><br>
+  Live latency, stability and verdicts for 228 models from 24 free AI providers, then install the one you pick straight into your favorite coding tool.<br><br>
   <strong>Works with:</strong> OpenCode CLI / Desktop / WebUI, OpenClaw, Crush, Goose, Aider, Kilo CLI, Qwen Code, OpenHands, Amp, Hermes, Continue, Cline, Xcode, Pi, ZCode, ForgeCode, Copilot, jcode, Caveman Code and more.
 </p>
 
@@ -35,7 +35,7 @@ free-coding-models
 
 ## 💡 Why this tool?
 
-There is a large catalog of free and free-limited coding models (**24 providers / 229 live models**, generated from [`sources.js`](./sources.js)). Which one is fastest *right now*? Which one is actually stable, versus just lucky on the last ping?
+There is a large catalog of free and free-limited coding models (**24 providers / 228 live models**, generated from [`sources.js`](./sources.js)). Which one is fastest *right now*? Which one is actually stable, versus just lucky on the last ping?
 
 `free-coding-models` (FCM) answers that by pinging every model in parallel, showing live latency, and computing a **live Stability Score (0-100)** combining p95 latency, jitter, spike rate and uptime. Average latency alone is misleading: a model that randomly spikes to 6 seconds is not reliable.
 
@@ -87,7 +87,7 @@ free-coding-models --fiable              # print the single most reliable model
 
 ## 🟢 Providers
 
-**24 active providers / 229 live models**, sorted by live model count. Top 8:
+**24 active providers / 228 live models**, sorted by live model count. Top 8:
 
 | Provider | Models | Best tier | Env var |
 |----------|--------|-----------|---------|
@@ -96,7 +96,7 @@ free-coding-models --fiable              # print the single most reliable model
 | [OpenRouter](https://openrouter.ai/keys) | 19 | S+ | `OPENROUTER_API_KEY` |
 | [Cloudflare AI](https://dash.cloudflare.com) | 15 | S | `CLOUDFLARE_API_TOKEN` |
 | [Kilo](https://kilo.ai) | 14 | S+ | `KILO_API_KEY` |
-| [NVIDIA NIM](https://build.nvidia.com) | 14 | S+ | `NVIDIA_API_KEY` |
+| [NVIDIA NIM](https://build.nvidia.com) | 13 | S+ | `NVIDIA_API_KEY` |
 | [Pollinations AI](https://enter.pollinations.ai) | 13 | S+ | `POLLINATIONS_API_KEY` |
 | [OVHcloud AI](https://endpoints.ai.cloud.ovh.net) | 12 | S+ | `OVH_AI_ENDPOINTS_ACCESS_TOKEN` |
 

package/changelog/v0.5.90.md

@@ -0,0 +1,12 @@
+# Changelog v0.5.90 - 2026-09-09
+
+### Fixed
+
+- **OpenCode Zen: every model probed `down` (HTTP 400) since 2026-09-07** (issue #181). Zen now gates its free tier behind an `x-opencode-session` header and answered `400 MissingSessionID` without it. We now send a stable per-process session uuid on every path that reaches the Zen gateway: TUI/CLI probes, router health probes and forwarded traffic, web dashboard benchmark + proxy routes, and key-tester model discovery. Verified live: `400 MissingSessionID` without the header, `200` with a real completion once it is present.
+- **Cloudflare Workers AI: every model probed `down` (HTTP 404)** (issue #181). The Workers AI endpoint is account-scoped, and we were failing that twice: two web dashboard paths (benchmark SSE, playground direct route) posted the raw catalog URL with the literal `{$CLOUDFLARE_ACCOUNT_ID}` placeholder, and every other path silently depended on the `CLOUDFLARE_ACCOUNT_ID` env var being visible in the probing process, which detached daemons and Docker never have. New `src/core/cloudflare-account.js` centralizes resolution: env var first, then stored settings (`settings.cloudflareAccountId`), then zero-setup auto-discovery from your API key via `GET /accounts` (cached in-process and persisted, so it runs once). The provider now works with just an API key, no env var needed. Key-tester live model discovery resolves the URL too.
+- **NVIDIA: removed MiniMax M3** - the model answered `410 Gone` with an explicit end-of-life timestamp of 2026-09-09. All 13 remaining NIM models were re-verified against the live API (9 x `200` today, 4 temporarily capacity-starved but alive).
+
+### Changed
+
+- **NVIDIA NIM catalog audit documented in `sources.js`** (issue #181, part 2). The issue flagged 67 NVIDIA models missing from our catalog; a live audit of all 80 ids in NIM's public `/v1/models` list shows that catalog is stale: every one of the 33 chat-capable candidates we do not track answers `404 Function not found` to a real chat completion (several were already removed on 2026-08-30 for exactly that signature). The catalog stays at the 13 live-verified models, and a dated audit comment now documents this so the ghost ids are not re-probed blindly.
+- **Docs**: `docs/providers.md` now notes the Zen session-header requirement and the Cloudflare account-id resolution order (env var > stored settings > auto-discovery). README model counts updated (229 -> 228 live models).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.89",
-  "description": "Find the fastest coding LLM models in seconds \u2014 ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
+  "version": "0.5.90",
+  "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",
     "nim",

package/sources.js

@@ -40,6 +40,10 @@
 
 // 📖 NIM source - https://build.nvidia.com
 export const nvidiaNim = [
+  // Audit (2026-09-09): GET /v1/models lists 80 ids but most are ghost catalog entries that
+  // answer 404 "Function not found" to a 1-token chat completion on the free integrate API.
+  // All 46 chat-capable candidates were probed live: only the models kept below respond, so
+  // ghost ids stay out even though the public catalog lists them (issue #181).
   // ── S+ tier — SWE-bench Verified ≥70% ──
   // Removed (2026-08-23): z-ai/glm-5.2 (GLM 5.1) — no longer in integrate.api.nvidia.com/v1/models (102 models live)
   // Removed (2026-09-05): moonshotai/kimi-k2.6 (Kimi K2.6) - Model page returns 404 and model is absent from the NVIDIA model catalog; could not verify existence
@@ -55,8 +59,7 @@ export const nvidiaNim = [
   // Removed (2026-07-27): meta/llama-4-maverick-17b-128e-instruct (Llama 4 Maverick) — EOL 2026-07-27 (HTTP 410 Gone)
   // Removed (2026-08-23): mistralai/mistral-medium-3.5-128b (Mistral Medium 3.5) — no longer in integrate.api.nvidia.com/v1/models (still on Mistral LP directly)
   // Removed (2026-07-27): mistralai/mistral-small-4-119b-2603 (Mistral Small 4) — EOL 2026-07-27 (HTTP 410 Gone)
-  // ⚠️ DEPRECATED - NVIDIA shutdown 2026-09-08
-  ['minimaxai/minimax-m3', 'MiniMax M3', 'S+', '78.4%', '1M'],
+  // Removed (2026-09-09): minimaxai/minimax-m3 (MiniMax M3) - 410 Gone per live chat probe: reached end of life 2026-09-09T09:00:00Z (shutdown was announced in-file on 2026-09-08)
   ['moonshotai/kimi-k3', 'Kimi K3', 'S', '-', '1M'], // Added (2026-09-02) — new in NIM catalog
   ['mistralai/mistral-nemotron', 'Mistral Nemotron', 'S', '-', '128k'], // Fixed ID (2026-07-27): nvidia/mistral-nemotron → mistralai/mistral-nemotron
   // Removed (2026-07-27): deepseek-ai/deepseek-v3.2 (DeepSeek V3.2) — HTTP 404

package/src/core/benchmark.js

@@ -25,12 +25,14 @@
  *
  *   📦 Dependencies:
  *   - ./ping.js: buildPingRequest, resolveCloudflareUrl
+ *   - ./cloudflare-account.js: ensureCloudflareAccountId (Cloudflare account discovery)
  *
  *   @see {@link ./ping.js} Provider-specific request building
  *   @see {@link ./render-table.js} AI Latency + TPS column rendering
  */
 
 import { buildPingRequest, resolveCloudflareUrl } from './ping.js'
+import { ensureCloudflareAccountId } from './cloudflare-account.js'
 
 // 📖 BENCHMARK_PROMPT: A deterministic one-paragraph task that any model can answer.
 // 📖 The longer target gives latency + TPS measurements enough generated tokens to be reliable.
@@ -258,6 +260,13 @@ async function benchmarkSingleAttempt({ apiKey, modelId, providerKey, url, timeo
 // 📖   { ok: false, code, totalMs, error, retries }
 export async function benchmarkModel({ apiKey, modelId, providerKey, url, timeoutMs = BENCHMARK_TIMEOUT_MS, maxRetries = BENCHMARK_MAX_RETRIES, retryDelayMs = BENCHMARK_RETRY_DELAY_MS }) {
 
+  // 📖 Cloudflare zero-setup (issue #181): let the account-id resolver run its
+  // 📖 one-time auto-discovery before any attempt so buildBenchmarkRequest's
+  // 📖 sync URL substitution sees a real account id instead of 'missing-account-id'.
+  if (providerKey === 'cloudflare') {
+    await ensureCloudflareAccountId()
+  }
+
   let lastResult = null
 
   for (let attempt = 0; attempt < maxRetries; attempt++) {

package/src/core/cloudflare-account.js

@@ -0,0 +1,311 @@
+/**
+ * @file cloudflare-account.js
+ * @description Central Cloudflare account-id resolution for the account-scoped Workers AI endpoint.
+ *
+ * @details
+ *   WHY: Cloudflare's OpenAI-compatible endpoint is per-account
+ *   (`https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/chat/completions`).
+ *   The catalog URL in sources.js therefore carries a `{$CLOUDFLARE_ACCOUNT_ID}`
+ *   placeholder, and every request path must replace it with a real account id
+ *   before hitting the API. A literal or missing id makes Cloudflare's router
+ *   return 404 for every model, 100% of the time (issue #181).
+ *
+ *   Resolution order (first hit wins):
+ *     1. `CLOUDFLARE_ACCOUNT_ID` env var
+ *     2. In-process cache (a previously resolved or discovered id)
+ *     3. Stored config `settings.cloudflareAccountId` (~/.free-coding-models.json)
+ *     4. Auto-discovery: GET /client/v4/accounts with the stored Cloudflare API key
+ *        (env CLOUDFLARE_API_TOKEN/CLOUDFLARE_API_KEY or config apiKeys.cloudflare);
+ *        the first account's id is cached in-process AND persisted to the config
+ *        settings so discovery only ever happens once. Best-effort: on failure the
+ *        old 'missing-account-id' behavior is kept and discovery backs off for
+ *        DISCOVERY_RETRY_COOLDOWN_MS so probes never hammer the endpoint.
+ *
+ *   The pure decision helpers (env / settings / discovery-payload / URL substitution)
+ *   are exported separately so tests can cover every branch hermetically with
+ *   injected dependencies, no network and no real config file.
+ *
+ *   📖 Note: `settings.cloudflareAccountId` is intentionally NOT added to
+ *   normalizeSettingsSection() in config.js: unknown settings keys pass through the
+ *   spread, so a stale process that loaded its config before discovery never clobbers
+ *   the persisted id on its next saveConfig() (it does not carry the key at all).
+ *
+ * @functions
+ *   → `pickAccountIdFromEnv(env)` - pure: trimmed CLOUDFLARE_ACCOUNT_ID or null
+ *   → `pickAccountIdFromSettings(settings)` - pure: stored settings.cloudflareAccountId or null
+ *   → `pickAccountIdFromDiscoveryResponse(payload)` - pure: first account id from a /accounts JSON body
+ *   → `applyCloudflareAccountId(url, accountId)` - pure: substitute the URL placeholders (encode + safe fallback)
+ *   → `getCloudflareAccountIdSync(deps)` - sync env > cache > stored-config resolution
+ *   → `ensureCloudflareAccountId(deps)` - async: sync resolution, then best-effort discovery (cached + persisted)
+ *   → `resolveCloudflareUrlAsync(url, deps)` - async: resolve the URL after guaranteeing an account id
+ *   → `resetCloudflareAccountStateForTests()` - clear in-process caches between tests
+ *
+ * @exports CLOUDFLARE_ACCOUNTS_URL, pickAccountIdFromEnv, pickAccountIdFromSettings,
+ *          pickAccountIdFromDiscoveryResponse, applyCloudflareAccountId,
+ *          getCloudflareAccountIdSync, ensureCloudflareAccountId, resolveCloudflareUrlAsync,
+ *          resetCloudflareAccountStateForTests
+ *
+ * @see src/core/ping.js - resolveCloudflareUrl (sync wrapper) + ping() probe path
+ * @see web/server.js - benchmark SSE + playground direct-route request paths
+ * @see issue #181 - why every cloudflare model probed as 404
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { CONFIG_PATH, saveConfig } from './config.js'
+
+// 📖 Cloudflare account-list endpoint: a plain GET with the API key as Bearer
+// 📖 returns the accounts the token can access; the first id is what probes need.
+export const CLOUDFLARE_ACCOUNTS_URL = 'https://api.cloudflare.com/client/v4/accounts'
+
+// 📖 Fallback segment kept identical to ping.js's historical behavior so verdicts,
+// 📖 docs and error messages stay stable when no account id can be resolved.
+const MISSING_ACCOUNT_ID = 'missing-account-id'
+
+// 📖 Discovery is best-effort: short timeout so probes never stall on it, and a
+// 📖 cooldown after failures so a broken key does not turn every ping into a
+// 📖 /accounts round-trip.
+const DISCOVERY_TIMEOUT_MS = 8000
+const DISCOVERY_RETRY_COOLDOWN_MS = 5 * 60 * 1000
+
+// 📖 In-process state: a resolved id is stable for the lifetime of the process,
+// 📖 so cache aggressively and dedupe concurrent discoveries.
+let cachedAccountId = null
+let diskSettingsLoaded = false
+let diskAccountId = null
+let discoveryInFlight = null
+// 📖 null = no failure yet; a timestamp (per the injectable clock) once a
+// 📖 discovery attempt failed, so back-off works with any clock source.
+let lastDiscoveryFailureAt = null
+
+/**
+ * 📖 Pure: read the account id from an env-style object. Trimmed, or null.
+ * @param {NodeJS.ProcessEnv | Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function pickAccountIdFromEnv(env = process.env) {
+  const raw = typeof env.CLOUDFLARE_ACCOUNT_ID === 'string' ? env.CLOUDFLARE_ACCOUNT_ID.trim() : ''
+  return raw || null
+}
+
+/**
+ * 📖 Pure: read the account id from a stored settings section. Trimmed, or null.
+ * @param {Record<string, unknown>|undefined} settings
+ * @returns {string|null}
+ */
+export function pickAccountIdFromSettings(settings) {
+  const raw = settings && typeof settings.cloudflareAccountId === 'string'
+    ? settings.cloudflareAccountId.trim()
+    : ''
+  return raw || null
+}
+
+/**
+ * 📖 Pure: extract the first usable account id from a /accounts JSON response.
+ * 📖 Cloudflare answers { success: true, result: [{ id: '...' }, ...] } on success
+ * 📖 and { success: false, errors: [...] } on auth failures; both must be safe.
+ * @param {unknown} payload
+ * @returns {string|null}
+ */
+export function pickAccountIdFromDiscoveryResponse(payload) {
+  if (!payload || typeof payload !== 'object' || payload.success !== true) return null
+  const accounts = Array.isArray(payload.result) ? payload.result : []
+  for (const account of accounts) {
+    const id = account && typeof account.id === 'string' ? account.id.trim() : ''
+    if (id) return id
+  }
+  return null
+}
+
+/**
+ * 📖 Pure: substitute the account-id placeholders in a catalog URL.
+ * 📖 Encodes the id so odd characters can never break the path, falls back to
+ * 📖 the historical 'missing-account-id' segment, and leaves URLs without a
+ * 📖 placeholder completely untouched.
+ * @param {string} url
+ * @param {string|null} accountId
+ * @returns {string}
+ */
+export function applyCloudflareAccountId(url, accountId) {
+  const hasPlaceholder = url.includes('{$CLOUDFLARE_ACCOUNT_ID}') || url.includes('{account_id}')
+  if (!hasPlaceholder) return url
+  const replacement = accountId ? encodeURIComponent(accountId) : MISSING_ACCOUNT_ID
+  return url
+    .replace(/\{\$CLOUDFLARE_ACCOUNT_ID\}/g, replacement)
+    .replace(/\{account_id\}/g, replacement)
+}
+
+// 📖 One-shot read of the stored settings.cloudflareAccountId from the config
+// 📖 file. Deliberately a raw readFileSync (no loadConfig side effects like
+// 📖 auto-repair or console noise) because this runs on every probe path.
+function readDiskSettings() {
+  if (diskSettingsLoaded) return diskAccountId
+  diskSettingsLoaded = true
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      const parsed = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+      diskAccountId = pickAccountIdFromSettings(parsed?.settings)
+    }
+  } catch {
+    // 📖 Corrupt or unreadable config - behave as if nothing is stored.
+  }
+  return diskAccountId
+}
+
+/**
+ * 📖 Sync resolution: env var, then in-process cache, then stored config.
+ * 📖 Used by every synchronous URL builder (ping request builder, benchmarks,
+ * 📖 router daemon, tool launchers, endpoint installer).
+ * @param {{ env?: NodeJS.ProcessEnv|Record<string, string|undefined>, settingsProvider?: () => string|null }} [deps]
+ * @returns {string|null}
+ */
+export function getCloudflareAccountIdSync({ env = process.env, settingsProvider = readDiskSettings } = {}) {
+  const fromEnv = pickAccountIdFromEnv(env)
+  if (fromEnv) {
+    cachedAccountId = fromEnv
+    return fromEnv
+  }
+  if (cachedAccountId) return cachedAccountId
+  const stored = settingsProvider()
+  if (stored) {
+    cachedAccountId = stored
+    return stored
+  }
+  return null
+}
+
+/**
+ * 📖 Best-effort persistence of a discovered id into the config settings so
+ * 📖 discovery only happens once per machine, not once per process.
+ * 📖 Reads a fresh snapshot right before saving to minimize clobber risk.
+ * @param {string} accountId
+ * @returns {void}
+ */
+function persistAccountIdToDisk(accountId) {
+  try {
+    if (!existsSync(CONFIG_PATH)) return
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+    if (!parsed || typeof parsed !== 'object') return
+    if (!parsed.settings || typeof parsed.settings !== 'object') parsed.settings = {}
+    if (parsed.settings.cloudflareAccountId === accountId) return
+    parsed.settings.cloudflareAccountId = accountId
+    saveConfig(parsed)
+  } catch {
+    // 📖 Persistence is an optimization; resolution still works in-process.
+  }
+}
+
+// 📖 Discovery API key: same candidates as config.js's ENV_VARS.cloudflare,
+// 📖 falling back to the stored config key (string or multi-key array).
+function readDiscoveryApiKey({ env, storedApiKeyProvider }) {
+  for (const candidate of ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_API_KEY']) {
+    const raw = typeof env[candidate] === 'string' ? env[candidate].trim() : ''
+    if (raw) return raw
+  }
+  return storedApiKeyProvider() || null
+}
+
+function readStoredApiKeyFromDisk() {
+  try {
+    if (!existsSync(CONFIG_PATH)) return null
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+    const stored = parsed?.apiKeys?.cloudflare
+    if (Array.isArray(stored)) {
+      const first = stored.find(k => typeof k === 'string' && k.length > 0)
+      return first ?? null
+    }
+    return typeof stored === 'string' && stored ? stored : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 📖 Async orchestrator: resolve via env/cache/config, then discover.
+ * 📖 Inject every dependency in tests - never let tests touch the network.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv|Record<string, string|undefined>,
+ *   settingsProvider?: () => string|null,
+ *   apiKey?: string|null,
+ *   storedApiKeyProvider?: () => string|null,
+ *   fetchImpl?: typeof fetch,
+ *   persist?: (accountId: string) => void,
+ *   now?: () => number,
+ * }} [deps]
+ * @returns {Promise<string|null>} the resolved id, or null (caller keeps 'missing-account-id')
+ */
+export async function ensureCloudflareAccountId({
+  env = process.env,
+  settingsProvider = readDiskSettings,
+  apiKey = undefined,
+  storedApiKeyProvider = readStoredApiKeyFromDisk,
+  fetchImpl = globalThis.fetch,
+  persist = persistAccountIdToDisk,
+  now = Date.now,
+} = {}) {
+  const existing = getCloudflareAccountIdSync({ env, settingsProvider })
+  if (existing) return existing
+
+  const key = apiKey !== undefined ? apiKey : readDiscoveryApiKey({ env, storedApiKeyProvider })
+  // 📖 No key means discovery cannot authenticate: stay in fail-safe mode
+  // 📖 instead of firing an always-401 request on every probe.
+  if (!key) return null
+
+  // 📖 After a failure, back off so probe loops never hammer /accounts.
+  if (lastDiscoveryFailureAt !== null && now() - lastDiscoveryFailureAt < DISCOVERY_RETRY_COOLDOWN_MS) return null
+
+  // 📖 Dedupe concurrent probes: share one in-flight discovery.
+  if (discoveryInFlight) return discoveryInFlight
+
+  discoveryInFlight = (async () => {
+    try {
+      const resp = await fetchImpl(CLOUDFLARE_ACCOUNTS_URL, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${key}` },
+        signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
+      })
+      let payload = null
+      try { payload = await resp.json() } catch { /* non-JSON error body */ }
+      const id = resp.ok ? pickAccountIdFromDiscoveryResponse(payload) : null
+      if (id) {
+        cachedAccountId = id
+        persist(id)
+        return id
+      }
+      lastDiscoveryFailureAt = now()
+      return null
+    } catch {
+      // 📖 Network error, timeout or abort: fail safe, back off.
+      lastDiscoveryFailureAt = now()
+      return null
+    } finally {
+      discoveryInFlight = null
+    }
+  })()
+  return discoveryInFlight
+}
+
+/**
+ * 📖 Async URL resolution for request paths that are already async: guarantee
+ * 📖 an account id (running discovery if needed) before substituting. Every
+ * 📖 caller that POSTs to the Cloudflare endpoint should go through this or
+ * 📖 through ping's sync resolveCloudflareUrl after ensure has run.
+ * @param {string} url
+ * @param {Parameters<typeof ensureCloudflareAccountId>[0]} [deps]
+ * @returns {Promise<string>}
+ */
+export async function resolveCloudflareUrlAsync(url, deps = {}) {
+  const accountId = await ensureCloudflareAccountId(deps)
+  return applyCloudflareAccountId(url, accountId)
+}
+
+/**
+ * 📖 Test-only: clear all in-process state so tests stay hermetic.
+ * @returns {void}
+ */
+export function resetCloudflareAccountStateForTests() {
+  cachedAccountId = null
+  diskSettingsLoaded = false
+  diskAccountId = null
+  discoveryInFlight = null
+  lastDiscoveryFailureAt = null
+}

package/src/core/endpoint-installer.js

@@ -45,6 +45,7 @@ import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { MODELS, sources } from '../../sources.js'
 import { getApiKey, saveConfig } from './config.js'
+import { getCloudflareAccountIdSync } from './cloudflare-account.js'
 import { ENV_VAR_NAMES, PROVIDER_METADATA } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 import { ensureDir, readJson as sharedReadJson, shellSingleQuote, atomicWriteJson } from './shared-helpers.js'
@@ -180,7 +181,9 @@ function resolveProviderBaseUrl(providerKey) {
   if (!providerUrl) return null
 
   if (providerKey === 'cloudflare') {
-    const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+    // 📖 Shared account-id resolution (issue #181): env var, in-process cache or
+    // 📖 stored config settings, so installs work without exporting the env var.
+    const accountId = getCloudflareAccountIdSync() || ''
     if (!accountId) return null
     return providerUrl
       .replace(/\{\$CLOUDFLARE_ACCOUNT_ID\}/g, encodeURIComponent(accountId))
@@ -201,7 +204,8 @@ function resolveGooseBaseUrl(providerKey) {
   const providerUrl = sources[providerKey]?.url
   if (!providerUrl) return null
   if (providerKey === 'cloudflare') {
-    const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+    // 📖 Shared account-id resolution (issue #181): env var, cache or stored config.
+    const accountId = getCloudflareAccountIdSync() || ''
     if (!accountId) return null
     return providerUrl
       .replace(/\{\$CLOUDFLARE_ACCOUNT_ID\}/g, encodeURIComponent(accountId))
@@ -218,8 +222,8 @@ function getDirectInstallSupport(providerKey) {
   if (DIRECT_INSTALL_UNSUPPORTED_PROVIDERS.has(providerKey)) {
     return { supported: false, reason: 'This provider still needs a dedicated runtime bridge' }
   }
-  if (providerKey === 'cloudflare' && !(process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()) {
-    return { supported: false, reason: 'CLOUDFLARE_ACCOUNT_ID is required for direct installs' }
+  if (providerKey === 'cloudflare' && !getCloudflareAccountIdSync()) {
+    return { supported: false, reason: 'Cloudflare account id required: set CLOUDFLARE_ACCOUNT_ID (or let auto-discovery find it from your API key)' }
   }
   return { supported: true, reason: null }
 }

package/src/core/opencode.js

@@ -32,6 +32,7 @@ import { PROVIDER_COLOR } from '../tui/render-table.js'
 import { sources } from '../../sources.js'
 import { loadOpenCodeConfig, saveOpenCodeConfig } from './opencode-config.js'
 import { getApiKey } from './config.js'
+import { getCloudflareAccountIdSync } from './cloudflare-account.js'
 import { ENV_VAR_NAMES, OPENCODE_MODEL_MAP, isWindows, isMac, isLinux } from './provider-metadata.js'
 import { resolveToolBinaryPath } from './tool-bootstrap.js'
 
@@ -512,10 +513,11 @@ export async function startOpenCode(model, fcmConfig) {
         models: {}
       }
     } else if (providerKey === 'cloudflare') {
-      const cloudflareAccountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+      // 📖 Shared account-id resolution (issue #181): env var, cache or stored config.
+      const cloudflareAccountId = getCloudflareAccountIdSync() || ''
       if (!cloudflareAccountId) {
-        console.log(chalk.yellow('  Cloudflare Workers AI requires CLOUDFLARE_ACCOUNT_ID for OpenCode integration.'))
-        console.log(chalk.dim('    Export CLOUDFLARE_ACCOUNT_ID and retry this selection.'))
+        console.log(chalk.yellow('  Cloudflare Workers AI needs an account id for OpenCode integration.'))
+        console.log(chalk.dim('    Export CLOUDFLARE_ACCOUNT_ID and retry (or ping a Cloudflare model once so the account id is auto-discovered from your API key).'))
         console.log()
         return
       }
@@ -911,10 +913,11 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
         models: {}
       }
     } else if (providerKey === 'cloudflare') {
-      const cloudflareAccountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+      // 📖 Shared account-id resolution (issue #181): env var, cache or stored config.
+      const cloudflareAccountId = getCloudflareAccountIdSync() || ''
       if (!cloudflareAccountId) {
-        console.log(chalk.yellow('  Cloudflare Workers AI requires CLOUDFLARE_ACCOUNT_ID for OpenCode integration.'))
-        console.log(chalk.dim('    Export CLOUDFLARE_ACCOUNT_ID and retry this selection.'))
+        console.log(chalk.yellow('  Cloudflare Workers AI needs an account id for OpenCode integration.'))
+        console.log(chalk.dim('    Export CLOUDFLARE_ACCOUNT_ID and retry (or ping a Cloudflare model once so the account id is auto-discovered from your API key).'))
         console.log()
         return
       }

package/src/core/ping.js

@@ -8,17 +8,20 @@
  *   endpoint quota polling with caching.
  *
  *   🎯 Key features:
- *   - Provider-specific request building (handles Replicate, Cloudflare, OpenRouter)
+ *   - Provider-specific request building (handles Replicate, Cloudflare, OpenRouter,
+ *     OpenCode Zen mandatory session header)
  *   - Async ping with timeout and abort controller
  *   - Quota extraction from rate limit headers (multiple variants supported)
  *   - Cached provider quota polling with TTL and error backoff
- *   - Cloudflare account ID resolution from environment
+ *   - Cloudflare account-id resolution from env var, stored config or zero-setup
+ *     auto-discovery via the /accounts endpoint (see ./cloudflare-account.js)
  *   - Per-provider circuit-breaker on 429 (issue #146): pauses ALL models of a provider
  *     when the provider returns a quota-exhausted response, so the ping loop stops
  *     hammering the user's daily quota while the provider's retry window is active.
  *
  *   → Functions:
- *   - `resolveCloudflareUrl`: Resolve {account_id} placeholder from CLOUDFLARE_ACCOUNT_ID env var
+ *   - `getProviderSessionHeaders`: Extra mandatory headers per provider (e.g. OpenCode Zen session id)
+ *   - `resolveCloudflareUrl`: Resolve {account_id} placeholders (env > cache > stored config, issue #181)
  *   - `buildChatCompletionPingBody`: Build minimal chat-completion probe payloads with thinking disabled
  *   - `markDisabledThinkingUnsupported`: Cache strict providers that reject the optional thinking control
  *   - `shouldUseDisabledThinkingForProvider`: Decide whether a provider should receive disabled-thinking probes
@@ -38,13 +41,21 @@
  *
  *   ⚙️ Configuration:
  *   - PING_TIMEOUT: Timeout in ms for ping requests (default: 15000)
- *   - CLOUDFLARE_ACCOUNT_ID: Env var for Cloudflare Workers AI account ID
+ *   - CLOUDFLARE_ACCOUNT_ID: Env var for the Cloudflare Workers AI account id
+ *     (fallbacks: stored settings.cloudflareAccountId, then auto-discovery via
+ *     the /accounts endpoint, handled in ./cloudflare-account.js)
  *
  *   @see {@link ../src/provider-quota-fetchers.js} Quota fetching implementation
  *   @see {@link ../src/quota-capabilities.js} Quota telemetry + Usage behavior detection
  */
 
+import { randomUUID } from 'node:crypto'
 import { PING_TIMEOUT } from './constants.js'
+import {
+  applyCloudflareAccountId,
+  getCloudflareAccountIdSync,
+  ensureCloudflareAccountId,
+} from './cloudflare-account.js'
 import { fetchProviderQuota as _fetchProviderQuotaFromModule, extractQuota as _extractQuotaFromModule, processResponseHeaders as _processResponseHeadersFromModule } from './provider-quota-fetchers.js'
 import { supportsUsagePercent } from './quota-capabilities.js'
 import {
@@ -56,17 +67,15 @@ const DISABLED_THINKING_RETRY_STATUSES = new Set([400, 422])
 const disabledThinkingUnsupportedProviders = new Set()
 
 // 📖 resolveCloudflareUrl: Cloudflare's OpenAI-compatible endpoint is account-scoped.
-// 📖 We resolve the placeholder from the CLOUDFLARE_ACCOUNT_ID env var so provider
-// 📖 setup can stay simple in config. Supports both the `{account_id}` placeholder
-// 📖 and the explicit `{$CLOUDFLARE_ACCOUNT_ID}` form used in sources.js.
-export function resolveCloudflareUrl(url) {
-  const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
-  const hasPlaceholder = url.includes('{$CLOUDFLARE_ACCOUNT_ID}') || url.includes('{account_id}')
-  if (!hasPlaceholder) return url
-  const replacement = accountId ? encodeURIComponent(accountId) : 'missing-account-id'
-  return url
-    .replace(/\{\$CLOUDFLARE_ACCOUNT_ID\}/g, replacement)
-    .replace(/\{account_id\}/g, replacement)
+// 📖 We resolve the placeholder from the CLOUDFLARE_ACCOUNT_ID env var, the
+// 📖 in-process cache or the stored config settings (issue #181), so provider
+// 📖 setup can stay simple. Supports both the `{account_id}` placeholder and
+// 📖 the explicit `{$CLOUDFLARE_ACCOUNT_ID}` form used in sources.js.
+// 📖 When nothing resolves, the historical 'missing-account-id' segment keeps
+// 📖 verdicts stable. Async paths should call ensureCloudflareAccountId() first
+// 📖 so zero-setup auto-discovery can populate the cache (see ping()).
+export function resolveCloudflareUrl(url, options = {}) {
+  return applyCloudflareAccountId(url, getCloudflareAccountIdSync(options))
 }
 
 // 📖 buildChatCompletionPingBody: Use the smallest useful chat-completion probe.
@@ -97,6 +106,25 @@ export function shouldUseDisabledThinkingForProvider(providerKey) {
   return !disabledThinkingUnsupportedProviders.has(providerKey)
 }
 
+// 📖 getProviderSessionHeaders: extra mandatory headers a provider requires beyond
+// 📖 the standard Content-Type/Authorization pair, centralised so probes (ping.js),
+// 📖 the router daemon and the web dashboard all send identical headers instead of
+// 📖 duplicating per-provider knowledge (issue #181).
+// 📖 OpenCode Zen rejects every request without an `x-opencode-session` header with
+// 📖 HTTP 400 MissingSessionID ("OpenCode's free tier can only be used in OpenCode").
+// 📖 The Zen docs describe a stable per-conversation session id, so we generate ONE
+// 📖 uuid per process at module load: every request this process sends shares the
+// 📖 same identity, mirroring how the real OpenCode client behaves and keeping the
+// 📖 value stable across repeated probes.
+const OPENCODE_ZEN_SESSION_ID = randomUUID()
+
+export function getProviderSessionHeaders(providerKey) {
+  if (providerKey === 'opencode-zen') {
+    return { 'x-opencode-session': OPENCODE_ZEN_SESSION_ID }
+  }
+  return {}
+}
+
 // 📖 buildPingRequest: Build provider-specific ping request.
 // 📖 Handles Replicate's /v1/predictions format, Cloudflare's account_id in URL,
 // 📖 and standard OpenAI-compliant chat completions with provider-specific headers.
@@ -128,7 +156,7 @@ export function buildPingRequest(apiKey, modelId, providerKey, url, options = {}
     }
   }
 
-  const headers = { 'Content-Type': 'application/json' }
+  const headers = { 'Content-Type': 'application/json', ...getProviderSessionHeaders(providerKey) }
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`
   if (providerKey === 'openrouter') {
     // 📖 OpenRouter recommends optional app identification headers.
@@ -178,6 +206,14 @@ async function isDisabledThinkingRejected(resp, req) {
 // 📖 A 401 response still tells us the server is UP and gives us real latency.
 // 📖 Returns { code, ms, quotaPercent }
 export async function ping(apiKey, modelId, providerKey, url) {
+  // 📖 Cloudflare zero-setup (issue #181): before building the request, give the
+  // 📖 account-id resolver a chance to auto-discover the id from the stored API
+  // 📖 key. Done BEFORE the timer starts so a one-time discovery round-trip never
+  // 📖 pollutes the measured latency or races PING_TIMEOUT. No-op when the id is
+  // 📖 already known from env/cache/config.
+  if (providerKey === 'cloudflare') {
+    await ensureCloudflareAccountId()
+  }
   const ctrl  = new AbortController()
   const timer = setTimeout(() => ctrl.abort(), PING_TIMEOUT)
   const t0    = performance.now()