free-coding-models 0.5.88 → 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` |
 
@@ -151,6 +151,12 @@ free-coding-models --daemon-stop    # stop
 
 > 📖 **Full guide (probes, circuit breaker, failover, Playground, `--sync-set`, REST API):** [`docs/router.md`](./docs/router.md)
 
+### 🧪 Router v2 engine (built in)
+
+The router daemon now runs the hardened v2 engine internally: content-validated failover (a 200 with empty or garbage output is a failure and fails over), quota-aware routing with `Retry-After` pauses, persisted circuit breakers with a DEGRADED warning state, per-request decision traces, an Anthropic `/v1/messages` endpoint, and "test via router" actions that exercise the real routing chain. Same command, same port, same endpoints - existing setups upgrade by updating the package.
+
+Open the TUI with `Shift+V` (or the "Router v2" entry in the Web Dashboard) to see the live fallback chain, per-request attempt chains and run pinned-model tests (`Ctrl+T`). Docs: [`docs/router-v2.md`](./docs/router-v2.md).
+
 ---
 
 ## 📖 CLI Flags

package/bin/free-coding-models.js

@@ -118,7 +118,7 @@ async function main() {
   ensureFavoritesConfig(config);
 
   const isDevMode = isPackageDevMode();
-  const shouldEnforceUpdate = !cliArgs.daemonStopMode && !cliArgs.daemonStatusMode;
+  const shouldEnforceUpdate = !cliArgs.daemonStopMode && !cliArgs.daemonStatusMode && !cliArgs.routerV2StopMode && !cliArgs.routerV2StatusMode;
   const startupUpdate = shouldEnforceUpdate
     ? await enforceMandatoryStartupUpdate(config, {
       saveConfig,
@@ -168,7 +168,11 @@ async function main() {
     && !cliArgs.daemonMode
     && !cliArgs.daemonBackgroundMode
     && !cliArgs.daemonStopMode
-    && !cliArgs.daemonStatusMode;
+    && !cliArgs.daemonStatusMode
+    && !cliArgs.routerV2Mode
+    && !cliArgs.routerV2BackgroundMode
+    && !cliArgs.routerV2StopMode
+    && !cliArgs.routerV2StatusMode;
   try {
     await checkConfigSecurity({ autoFix: cliArgs.fixPermissionsMode, promptAllowed });
   } catch {
@@ -210,6 +214,33 @@ async function main() {
     process.exit(result.ok ? 0 : 1);
   }
 
+  // 📖 Router v2 lifecycle flags are now ALIASES of the main daemon: the v2
+  // engine (content-validated failover, persisted breakers, decision traces,
+  // Anthropic /v1/messages) is merged into the regular router daemon on the
+  // historical port. The flags keep working for existing scripts.
+  if (cliArgs.routerV2Mode || cliArgs.routerV2BackgroundMode || cliArgs.routerV2StopMode || cliArgs.routerV2StatusMode) {
+    const {
+      getRouterDaemonStatus,
+      runRouterDaemon,
+      startRouterDaemonBackground,
+      stopRouterDaemon,
+    } = await import('../src/core/router-daemon.js');
+
+    if (cliArgs.routerV2Mode) {
+      await runRouterDaemon();
+      return;
+    }
+
+    const result = cliArgs.routerV2BackgroundMode
+      ? await startRouterDaemonBackground()
+      : cliArgs.routerV2StopMode
+        ? await stopRouterDaemon()
+        : await getRouterDaemonStatus();
+
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  }
+
   // 📖 --sync-set [name] — auto-discover, probe, and populate a router set
   if (cliArgs.syncSetMode) {
     const { syncSet } = await import('../src/core/sync-set.js');

package/changelog/v0.5.89.md

@@ -0,0 +1,20 @@
+# Changelog v0.5.89 - 2026-09-06
+
+### Added
+- 🧪 **Smart Model Router v2 engine (built in)**: the regular router daemon (`--daemon-bg`, historical port) now runs the hardened v2 engine - same command, same port, same endpoints, existing setups upgrade transparently. A hardened parallel beta ran on port 19380 during development; it is retired by this release. Open the TUI overlay with `Shift+V`, or use the "Router v2" page in the Web Dashboard (BETA badge on both surfaces).
+- 🛡️ **Content-validated failover**: a 200 only counts as a success when the answer holds real content. Empty `choices`, embedded `error` objects or content-less replies now fail over to the next model, in both streaming and non-streaming. This closes the biggest v1 blind spot where free providers serving empty 200s were reported as successes.
+- ⏱️ **Body-read timeout**: a provider that sends headers but trickles (or never sends) the body can no longer hang your coding tool; the read is raced against `router.failover.bodyReadTimeoutMs` (default 30s) and fails over.
+- 🔥 **Quota-aware routing**: models answering 429 are paused for their `Retry-After` window and skipped; when every model is paused the client gets a proper `429` + `Retry-After` instead of a generic 503.
+- ⚖️ **Blame attribution**: client-caused 4xx (bad payload, unsupported fields) fail over but never damage healthy models' circuit breakers, and client disconnects never mark failures.
+- 💾 **Persisted circuit breakers**: breaker state survives daemon restarts, with a new amber `DEGRADED` warning state (60% of the failure threshold) and escalating cooldowns for repeatedly-tripping models.
+- 🔍 **Decision traces**: every response carries `x-fcm-v2-model`, `x-fcm-v2-attempts` and `x-fcm-v2-decision` headers, and every request chain (attempts, statuses, skip reasons) is persisted locally and rendered in the TUI overlay and the web page. Routing metadata only: no prompts, no keys.
+- 🤖 **Anthropic `/v1/messages` support** on the v2 port: request, response and SSE stream translation (including `tool_use` / `input_json_delta`), so Anthropic-protocol agents can use the router directly.
+- 📌 **Pinned-model requests**: `model: "fcm:@provider/modelId"` routes to one exact model through the full chain with failover disabled. New `Ctrl+T` (test selected model) and `Ctrl+Shift+T` (test all visible models) TUI hotkeys use it to test the real routing path, unlike the direct-to-provider `Ctrl+A` / `Ctrl+U` benchmarks.
+- 🚑 **Last-resort model**: optional `router.failover.lastResortModel` config gives a designated model one final shot when the whole set fails.
+- ⚡ **Fast first boot**: v2 listens before its first probe pass, removing the old first-boot stall where the router port stayed dark for up to ~36 seconds.
+
+### Security
+- 🔒 Client `x-api-key` headers are now stripped before proxying to upstream providers on v2, so the local router token can never leak to a provider.
+
+### Fixed
+- 🐛 Ghost "active requests" no longer accumulate in v2 stats when a request is rejected before routing (v1 leaks one entry per rejected request until restart).

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,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.88",
+  "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",

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
       }