free-coding-models 0.3.0 → 0.3.2

package/src/proxy-server.js

@@ -1,7 +1,7 @@
 /**
  * @file lib/proxy-server.js
  * @description Multi-account rotation proxy server with SSE streaming,
- * token stats tracking, and persistent request logging.
+ * token stats tracking, Anthropic/OpenAI translation, and persistent request logging.
  *
  * Design:
  *   - Binds to 127.0.0.1 only (never 0.0.0.0)
@@ -10,6 +10,8 @@
  *   - x-ratelimit-* headers are stripped from all responses forwarded to clients
  *   - Retry loop: first attempt uses sticky session fingerprint; subsequent
  *     retries use fresh P2C to avoid hitting the same failed account
+ *   - Claude-family aliases are resolved inside the proxy so Claude Code can
+ *     keep emitting `claude-*` / `sonnet` / `haiku` style model ids safely
  *
  * @exports ProxyServer
  */
@@ -25,7 +27,13 @@ import {
   translateAnthropicToOpenAI,
   translateOpenAIToAnthropic,
   createAnthropicSSETransformer,
+  estimateAnthropicTokens,
 } from './anthropic-translator.js'
+import {
+  translateResponsesToOpenAI,
+  translateOpenAIToResponses,
+  createResponsesSSETransformer,
+} from './responses-translator.js'
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -100,6 +108,49 @@ function sendJson(res, statusCode, body) {
   res.end(json)
 }
 
+function normalizeRequestedModel(modelId) {
+  if (typeof modelId !== 'string') return null
+  const trimmed = modelId.trim()
+  if (!trimmed) return null
+  return trimmed.replace(/^fcm-proxy\//, '')
+}
+
+function classifyClaudeVirtualModel(modelId) {
+  const normalized = normalizeRequestedModel(modelId)
+  if (!normalized) return null
+
+  const lower = normalized.toLowerCase()
+
+  // 📖 Mirror free-claude-code's family routing approach: classify by Claude
+  // 📖 family keywords, not only exact ids. Claude Code regularly emits both
+  // 📖 short aliases (`sonnet`) and full versioned ids (`claude-3-5-sonnet-*`).
+  if (lower === 'default') return 'default'
+  if (/^opus(?:plan)?(?:\[1m\])?$/.test(lower)) return 'opus'
+  if (/^sonnet(?:\[1m\])?$/.test(lower)) return 'sonnet'
+  if (lower === 'haiku') return 'haiku'
+  if (!lower.startsWith('claude-')) return null
+  if (lower.includes('opus')) return 'opus'
+  if (lower.includes('haiku')) return 'haiku'
+  if (lower.includes('sonnet')) return 'sonnet'
+  return null
+}
+
+function parseProxyAuthorizationHeader(authorization, expectedToken) {
+  if (!expectedToken) return { authorized: true, modelHint: null }
+  if (typeof authorization !== 'string' || !authorization.startsWith('Bearer ')) {
+    return { authorized: false, modelHint: null }
+  }
+
+  const rawToken = authorization.slice('Bearer '.length).trim()
+  if (rawToken === expectedToken) return { authorized: true, modelHint: null }
+  if (!rawToken.startsWith(`${expectedToken}:`)) return { authorized: false, modelHint: null }
+
+  const modelHint = normalizeRequestedModel(rawToken.slice(expectedToken.length + 1))
+  return modelHint
+    ? { authorized: true, modelHint }
+    : { authorized: false, modelHint: null }
+}
+
 // ─── ProxyServer ─────────────────────────────────────────────────────────────
 
 export class ProxyServer {
@@ -188,11 +239,32 @@ export class ProxyServer {
     }
   }
 
+  _getAuthContext(req) {
+    return parseProxyAuthorizationHeader(req.headers.authorization, this._proxyApiKey)
+  }
+
   _isAuthorized(req) {
-    if (!this._proxyApiKey) return true
-    const authorization = req.headers.authorization
-    if (typeof authorization !== 'string') return false
-    return authorization === `Bearer ${this._proxyApiKey}`
+    return this._getAuthContext(req).authorized
+  }
+
+  _resolveAnthropicRequestedModel(modelId, authModelHint = null) {
+    const requestedModel = normalizeRequestedModel(modelId)
+    if (requestedModel && this._accountManager.hasAccountsForModel(requestedModel)) {
+      return requestedModel
+    }
+
+    // 📖 Claude Code still emits internal aliases / tier model ids for some
+    // 📖 background and helper paths. When the launcher encoded the selected
+    // 📖 proxy slug into the auth token, remap those virtual Claude ids here.
+    // 📖 This intentionally matches Claude families by substring so ids like
+    // 📖 `claude-3-5-sonnet-20241022` behave the same as `sonnet`.
+    if (authModelHint && this._accountManager.hasAccountsForModel(authModelHint)) {
+      if (!requestedModel || classifyClaudeVirtualModel(requestedModel)) {
+        return authModelHint
+      }
+    }
+
+    return requestedModel
   }
 
   // ── Request routing ────────────────────────────────────────────────────────
@@ -203,7 +275,8 @@ export class ProxyServer {
       return this._handleHealth(res)
     }
 
-    if (!this._isAuthorized(req)) {
+    const authContext = this._getAuthContext(req)
+    if (!authContext.authorized) {
       return sendJson(res, 401, { error: 'Unauthorized' })
     }
 
@@ -221,13 +294,27 @@ export class ProxyServer {
       })
     } else if (req.method === 'POST' && req.url === '/v1/messages') {
       // 📖 Anthropic Messages API translation — enables Claude Code compatibility
-      this._handleAnthropicMessages(req, res).catch(err => {
+      this._handleAnthropicMessages(req, res, authContext).catch(err => {
+        console.error('[proxy] Internal error:', err)
+        const status = err.statusCode === 413 ? 413 : 500
+        const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
+        sendJson(res, status, { error: msg })
+      })
+    } else if (req.method === 'POST' && req.url === '/v1/messages/count_tokens') {
+      this._handleAnthropicCountTokens(req, res).catch(err => {
+        console.error('[proxy] Internal error:', err)
+        const status = err.statusCode === 413 ? 413 : 500
+        const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
+        sendJson(res, status, { error: msg })
+      })
+    } else if (req.method === 'POST' && req.url === '/v1/responses') {
+      this._handleResponses(req, res).catch(err => {
         console.error('[proxy] Internal error:', err)
         const status = err.statusCode === 413 ? 413 : 500
         const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
         sendJson(res, status, { error: msg })
       })
-    } else if (req.method === 'POST' && (req.url === '/v1/completions' || req.url === '/v1/responses')) {
+    } else if (req.method === 'POST' && req.url === '/v1/completions') {
       // These legacy/alternative OpenAI endpoints are not supported by the proxy.
       // Return 501 (not 404) so callers get a clear signal instead of silently failing.
       sendJson(res, 501, {
@@ -244,19 +331,24 @@ export class ProxyServer {
   _handleModels(res) {
     const seen = new Set()
     const data = []
+    const models = []
     for (const acct of this._accounts) {
       const publicModelId = acct.proxyModelId || acct.modelId
       if (!seen.has(publicModelId)) {
         seen.add(publicModelId)
-        data.push({
+        const modelEntry = {
           id: publicModelId,
+          slug: publicModelId,
+          name: publicModelId,
           object: 'model',
           created: Math.floor(Date.now() / 1000),
           owned_by: 'proxy',
-        })
+        }
+        data.push(modelEntry)
+        models.push(modelEntry)
       }
     }
-    sendJson(res, 200, { object: 'list', data })
+    sendJson(res, 200, { object: 'list', data, models })
   }
 
   // ── POST /v1/chat/completions ──────────────────────────────────────────────
@@ -708,7 +800,7 @@ export class ProxyServer {
    *
    * 📖 This makes Claude Code work natively through the FCM proxy.
    */
-  async _handleAnthropicMessages(clientReq, clientRes) {
+  async _handleAnthropicMessages(clientReq, clientRes, authContext = { modelHint: null }) {
     const rawBody = await readBody(clientReq)
     let anthropicBody
     try {
@@ -719,6 +811,8 @@ export class ProxyServer {
 
     // 📖 Translate Anthropic → OpenAI
     const openaiBody = translateAnthropicToOpenAI(anthropicBody)
+    const resolvedModel = this._resolveAnthropicRequestedModel(openaiBody.model, authContext.modelHint)
+    if (resolvedModel) openaiBody.model = resolvedModel
     const isStreaming = openaiBody.stream === true
 
     if (isStreaming) {
@@ -730,6 +824,146 @@ export class ProxyServer {
     }
   }
 
+  /**
+   * 📖 Count tokens for Anthropic Messages requests without calling upstream.
+   * 📖 Claude Code uses this endpoint for budgeting / UI hints, so a fast local
+   * 📖 estimate is enough to keep the flow working through the proxy.
+   */
+  async _handleAnthropicCountTokens(clientReq, clientRes) {
+    const rawBody = await readBody(clientReq)
+    let anthropicBody
+    try {
+      anthropicBody = JSON.parse(rawBody)
+    } catch {
+      return sendJson(clientRes, 400, { error: { type: 'invalid_request_error', message: 'Invalid JSON body' } })
+    }
+
+    sendJson(clientRes, 200, {
+      input_tokens: estimateAnthropicTokens(anthropicBody),
+    })
+  }
+
+  /**
+   * 📖 Handle OpenAI Responses API requests by translating them to chat
+   * 📖 completions, forwarding through the existing proxy path, then converting
+   * 📖 the result back to the Responses wire format.
+   */
+  async _handleResponses(clientReq, clientRes) {
+    const rawBody = await readBody(clientReq)
+    let responsesBody
+    try {
+      responsesBody = JSON.parse(rawBody)
+    } catch {
+      return sendJson(clientRes, 400, { error: 'Invalid JSON body' })
+    }
+
+    const isStreaming = responsesBody.stream === true || String(clientReq.headers.accept || '').includes('text/event-stream')
+    const openaiBody = translateResponsesToOpenAI({ ...responsesBody, stream: isStreaming })
+
+    if (isStreaming) {
+      await this._handleResponsesStreaming(openaiBody, responsesBody.model, clientRes)
+    } else {
+      await this._handleResponsesJson(openaiBody, responsesBody.model, clientRes)
+    }
+  }
+
+  async _handleResponsesJson(openaiBody, requestModel, clientRes) {
+    const capturedChunks = []
+    let capturedStatusCode = 200
+    let capturedHeaders = {}
+
+    const fakeRes = {
+      headersSent: false,
+      destroyed: false,
+      socket: null,
+      writeHead(statusCode, headers) {
+        capturedStatusCode = statusCode
+        capturedHeaders = headers || {}
+        this.headersSent = true
+      },
+      write(chunk) { capturedChunks.push(chunk) },
+      end(data) {
+        if (data) capturedChunks.push(data)
+      },
+      on() { return this },
+      once() { return this },
+      emit() { return false },
+      destroy() { this.destroyed = true },
+      removeListener() { return this },
+    }
+
+    await this._handleChatCompletionsInternal(openaiBody, fakeRes)
+
+    const responseBody = capturedChunks.join('')
+    if (capturedStatusCode >= 200 && capturedStatusCode < 300) {
+      try {
+        const openaiResponse = JSON.parse(responseBody)
+        const responsesResponse = translateOpenAIToResponses(openaiResponse, requestModel)
+        sendJson(clientRes, 200, responsesResponse)
+      } catch {
+        sendJson(clientRes, capturedStatusCode, responseBody)
+      }
+      return
+    }
+
+    // 📖 Forward upstream-style JSON errors unchanged for OpenAI-compatible clients.
+    sendJson(clientRes, capturedStatusCode, responseBody)
+  }
+
+  async _handleResponsesStreaming(openaiBody, requestModel, clientRes) {
+    const { transform } = createResponsesSSETransformer(requestModel)
+    await this._handleResponsesStreamDirect(openaiBody, clientRes, transform)
+  }
+
+  async _handleResponsesStreamDirect(openaiBody, clientRes, sseTransform) {
+    const fingerprint = createHash('sha256')
+      .update(JSON.stringify(openaiBody.messages?.slice(-1) ?? []))
+      .digest('hex')
+      .slice(0, 16)
+
+    const requestedModel = typeof openaiBody.model === 'string'
+      ? openaiBody.model.replace(/^fcm-proxy\//, '')
+      : undefined
+
+    if (requestedModel && !this._accountManager.hasAccountsForModel(requestedModel)) {
+      return sendJson(clientRes, 404, {
+        error: 'Model not found',
+        message: `Model '${requestedModel}' is not available.`,
+      })
+    }
+
+    sseTransform.pipe(clientRes)
+
+    for (let attempt = 0; attempt < this._retries; attempt++) {
+      const delay = this._retryDelays[Math.min(attempt, this._retryDelays.length - 1)]
+      if (delay > 0) await new Promise(r => setTimeout(r, delay + Math.random() * 100))
+
+      const selectOpts = attempt === 0
+        ? { sessionFingerprint: fingerprint, requestedModel }
+        : { requestedModel }
+      const account = this._accountManager.selectAccount(selectOpts)
+      if (!account) break
+
+      const result = await this._forwardRequestForResponsesStream(account, openaiBody, sseTransform, clientRes)
+      if (result.done) return
+
+      const { statusCode, responseBody, responseHeaders, networkError } = result
+      const classified = classifyError(
+        networkError ? 0 : statusCode,
+        responseBody || '',
+        responseHeaders || {}
+      )
+      this._accountManager.recordFailure(account.id, classified, { providerKey: account.providerKey })
+      if (!classified.shouldRetry) {
+        sseTransform.end()
+        return sendJson(clientRes, statusCode || 500, responseBody || JSON.stringify({ error: 'Upstream error' }))
+      }
+    }
+
+    sseTransform.end()
+    sendJson(clientRes, 503, { error: 'All accounts exhausted or unavailable' })
+  }
+
   /**
    * 📖 Handle non-streaming Anthropic Messages by internally dispatching to
    * chat completions logic and translating the JSON response back.
@@ -1002,6 +1236,95 @@ export class ProxyServer {
     })
   }
 
+  /**
+   * 📖 Forward a streaming chat-completions request and translate the upstream
+   * 📖 SSE stream into Responses API events on the fly.
+   */
+  _forwardRequestForResponsesStream(account, body, sseTransform, clientRes) {
+    return new Promise(resolve => {
+      const newBody = { ...body, model: account.modelId, stream: true }
+      const bodyStr = JSON.stringify(newBody)
+      const baseUrl = account.url.replace(/\/$/, '')
+      let upstreamUrl
+      try {
+        upstreamUrl = new URL(baseUrl + '/chat/completions')
+      } catch {
+        return resolve({ done: false, statusCode: 0, responseBody: 'Invalid upstream URL', networkError: true })
+      }
+
+      const client = selectClient(account.url)
+      const startTime = Date.now()
+      const requestOptions = {
+        hostname: upstreamUrl.hostname,
+        port: upstreamUrl.port || (upstreamUrl.protocol === 'https:' ? 443 : 80),
+        path: upstreamUrl.pathname + (upstreamUrl.search || ''),
+        method: 'POST',
+        headers: {
+          'authorization': `Bearer ${account.apiKey}`,
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(bodyStr),
+        },
+      }
+
+      const upstreamReq = client.request(requestOptions, upstreamRes => {
+        const { statusCode } = upstreamRes
+
+        if (statusCode >= 200 && statusCode < 300) {
+          if (!clientRes.headersSent) {
+            clientRes.writeHead(200, {
+              'content-type': 'text/event-stream',
+              'cache-control': 'no-cache',
+            })
+          }
+
+          upstreamRes.on('error', err => { if (!clientRes.destroyed) clientRes.destroy(err) })
+          clientRes.on('error', () => { if (!upstreamRes.destroyed) upstreamRes.destroy() })
+
+          upstreamRes.pipe(sseTransform, { end: true })
+          upstreamRes.on('end', () => {
+            this._accountManager.recordSuccess(account.id, Date.now() - startTime)
+          })
+
+          clientRes.on('close', () => {
+            if (!upstreamRes.destroyed) upstreamRes.destroy()
+            if (!upstreamReq.destroyed) upstreamReq.destroy()
+          })
+
+          resolve({ done: true })
+        } else {
+          const chunks = []
+          upstreamRes.on('data', chunk => chunks.push(chunk))
+          upstreamRes.on('end', () => {
+            resolve({
+              done: false,
+              statusCode,
+              responseBody: Buffer.concat(chunks).toString(),
+              responseHeaders: upstreamRes.headers,
+              networkError: false,
+            })
+          })
+        }
+      })
+
+      upstreamReq.on('error', err => {
+        resolve({
+          done: false,
+          statusCode: 0,
+          responseBody: err.message,
+          responseHeaders: {},
+          networkError: true,
+        })
+      })
+
+      upstreamReq.setTimeout(this._upstreamTimeoutMs, () => {
+        upstreamReq.destroy(new Error(`Upstream request timed out after ${this._upstreamTimeoutMs}ms`))
+      })
+
+      upstreamReq.write(bodyStr)
+      upstreamReq.end()
+    })
+  }
+
   /**
    * 📖 Internal version of chat completions handler that takes a pre-parsed body.
    * 📖 Used by the Anthropic JSON translation path to avoid re-parsing.

package/src/proxy-sync.js

@@ -14,9 +14,10 @@
  * @functions
  *   → syncProxyToTool(toolMode, proxyInfo, mergedModels) — write proxy endpoint to tool config
  *   → cleanupToolConfig(toolMode) — remove all FCM entries from tool config
+ *   → resolveProxySyncToolMode(toolMode) — normalize a live tool mode to a proxy-syncable target
  *   → getProxySyncableTools() — list of tools that support proxy sync
  *
- * @exports syncProxyToTool, cleanupToolConfig, getProxySyncableTools, PROXY_SYNCABLE_TOOLS
+ * @exports syncProxyToTool, cleanupToolConfig, resolveProxySyncToolMode, getProxySyncableTools, PROXY_SYNCABLE_TOOLS
  *
  * @see src/endpoint-installer.js — per-provider direct install (Y key flow)
  * @see src/opencode-sync.js — OpenCode-specific sync (used internally by this module)
@@ -38,6 +39,8 @@ export const PROXY_SYNCABLE_TOOLS = [
   'aider', 'amp', 'qwen', 'claude-code', 'codex', 'openhands',
 ]
 
+const PROXY_SYNCABLE_CANONICAL = new Set(PROXY_SYNCABLE_TOOLS.map(tool => tool === 'opencode-desktop' ? 'opencode' : tool))
+
 // ─── Shared helpers ──────────────────────────────────────────────────────────
 
 function getDefaultPaths() {
@@ -120,6 +123,12 @@ function getDefaultMaxTokens(contextWindow) {
   return Math.max(4096, Math.min(contextWindow, 32768))
 }
 
+export function resolveProxySyncToolMode(toolMode) {
+  if (typeof toolMode !== 'string' || toolMode.length === 0) return null
+  const canonical = toolMode === 'opencode-desktop' ? 'opencode' : toolMode
+  return PROXY_SYNCABLE_CANONICAL.has(canonical) ? canonical : null
+}
+
 // ─── Per-tool sync functions ─────────────────────────────────────────────────
 // 📖 Each writes a single `fcm-proxy` provider entry with ALL models
 
@@ -358,8 +367,8 @@ function syncEnvTool(proxyInfo, mergedModels, toolMode) {
  * @returns {{ success: boolean, path?: string, modelCount?: number, error?: string }}
  */
 export function syncProxyToTool(toolMode, proxyInfo, mergedModels) {
-  const canonical = toolMode === 'opencode-desktop' ? 'opencode' : toolMode
-  if (!PROXY_SYNCABLE_TOOLS.includes(toolMode) && !PROXY_SYNCABLE_TOOLS.includes(canonical)) {
+  const canonical = resolveProxySyncToolMode(toolMode)
+  if (!canonical) {
     return { success: false, error: `Tool '${toolMode}' does not support proxy sync` }
   }
 
@@ -415,7 +424,10 @@ export function syncProxyToTool(toolMode, proxyInfo, mergedModels) {
  * @returns {{ success: boolean, error?: string }}
  */
 export function cleanupToolConfig(toolMode) {
-  const canonical = toolMode === 'opencode-desktop' ? 'opencode' : toolMode
+  const canonical = resolveProxySyncToolMode(toolMode)
+  if (!canonical) {
+    return { success: false, error: `Tool '${toolMode}' does not support proxy cleanup` }
+  }
 
   try {
     const paths = getDefaultPaths()

package/src/render-helpers.js

@@ -150,10 +150,12 @@ export function sliceOverlayLines(lines, offset, terminalRows) {
 
 // 📖 calculateViewport: Computes the visible slice of model rows that fits in the terminal.
 // 📖 When scroll indicators are needed, they each consume 1 line from the model budget.
+// 📖 `extraFixedLines` lets callers reserve temporary footer rows without shrinking the
+// 📖 viewport permanently for the normal case.
 // 📖 Returns { startIdx, endIdx, hasAbove, hasBelow } for rendering.
-export function calculateViewport(terminalRows, scrollOffset, totalModels) {
+export function calculateViewport(terminalRows, scrollOffset, totalModels, extraFixedLines = 0) {
   if (terminalRows <= 0) return { startIdx: 0, endIdx: totalModels, hasAbove: false, hasBelow: false }
-  let maxSlots = terminalRows - TABLE_FIXED_LINES
+  let maxSlots = terminalRows - TABLE_FIXED_LINES - extraFixedLines
   if (maxSlots < 1) maxSlots = 1
   if (totalModels <= maxSlots) return { startIdx: 0, endIdx: totalModels, hasAbove: false, hasBelow: false }
 

package/src/render-table.js

@@ -15,6 +15,7 @@
  *   - Smart badges (mode, tier filter, origin filter, profile)
  *   - Footer J badge: green "Proxy On" / red "Proxy Off" indicator with direct overlay access
  *   - Install-endpoints shortcut surfaced directly in the footer hints
+ *   - Full-width red outdated-version banner when a newer npm release is known
  *   - Distinct auth-failure vs missing-key health labels so configured providers stay honest
  *
  *   → Functions:
@@ -40,7 +41,7 @@ import { TIER_COLOR } from './tier-colors.js'
 import { getAvg, getVerdict, getUptime, getStabilityScore, getVersionStatusInfo } from './utils.js'
 import { usagePlaceholderForProvider } from './ping.js'
 import { formatTokenTotalCompact } from './token-usage-reader.js'
-import { calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay } from './render-helpers.js'
+import { calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay, displayWidth } from './render-helpers.js'
 import { getToolMeta } from './tool-metadata.js'
 
 const ACTIVE_FILTER_BG_BY_TIER = {
@@ -92,7 +93,7 @@ export function setActiveProxy(proxyInstance) {
 }
 
 // ─── renderTable: mode param controls footer hint text (opencode vs openclaw) ─────────
-export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, isOutdated = false, latestVersion = null) {
+export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, startupLatestVersion = null, versionAlertsEnabled = true) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -140,7 +141,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     : chalk.bold.rgb(0, 200, 255)
   const modeBadge = toolBadgeColor(' [ ') + chalk.yellow.bold('Z') + toolBadgeColor(` Tool : ${toolMeta.label} ]`)
   const activeHeaderBadge = (text, bg = [57, 255, 20], fg = [0, 0, 0]) => chalk.bgRgb(...bg).rgb(...fg).bold(` ${text} `)
-  const versionStatus = getVersionStatusInfo(settingsUpdateState, settingsUpdateLatestVersion)
+  const versionStatus = getVersionStatusInfo(settingsUpdateState, settingsUpdateLatestVersion, startupLatestVersion, versionAlertsEnabled)
 
   // 📖 Tier filter badge shown when filtering is active (shows exact tier name)
   const TIER_CYCLE_NAMES = [null, 'S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
@@ -336,7 +337,8 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   }
 
   // 📖 Viewport clipping: only render models that fit on screen
-  const vp = calculateViewport(terminalRows, scrollOffset, sorted.length)
+  const extraFooterLines = versionStatus.isOutdated ? 1 : 0
+  const vp = calculateViewport(terminalRows, scrollOffset, sorted.length, extraFooterLines)
 
   if (vp.hasAbove) {
     lines.push(chalk.dim(`  ... ${vp.startIdx} more above ...`))
@@ -652,40 +654,36 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     hotkey('I', ' Feedback, bugs & requests')
   )
   // 📖 Proxy status is now shown via the J badge in line 2 above — no need for a dedicated line
-  if (versionStatus.isOutdated) {
-    const outdatedBadge = chalk.bgRed.bold.yellow(' This version is outdated . ')
-    const latestLabel = chalk.redBright(` local v${LOCAL_VERSION} · latest v${versionStatus.latestVersion}`)
-    lines.push(`  ${outdatedBadge}${latestLabel}`)
-  }
+  const footerLine =
+    chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
+    chalk.dim('  •  ') +
+    '⭐ ' +
+    chalk.yellow('\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\Star on GitHub\x1b]8;;\x1b\\') +
+    chalk.dim('  •  ') +
+    '🤝 ' +
+    chalk.rgb(255, 165, 0)('\x1b]8;;https://github.com/vava-nessa/free-coding-models/graphs/contributors\x1b\\Contributors\x1b]8;;\x1b\\') +
+    chalk.dim('  •  ') +
+    '☕ ' +
+    chalk.rgb(255, 200, 100)('\x1b]8;;https://buymeacoffee.com/vavanessadev\x1b\\Buy me a coffee\x1b]8;;\x1b\\') +
+    chalk.dim('  •  ') +
+    '💬 ' +
+    chalk.rgb(200, 150, 255)('\x1b]8;;https://discord.gg/ZTNFHvvCkU\x1b\\Discord\x1b]8;;\x1b\\') +
+    chalk.dim(' → ') +
+    chalk.rgb(200, 150, 255)('https://discord.gg/ZTNFHvvCkU') +
+    chalk.dim('  •  ') +
+    chalk.yellow('N') + chalk.dim(' Changelog') +
+    chalk.dim('  •  ') +
+    chalk.dim('Ctrl+C Exit')
+  lines.push(footerLine)
 
-  // 📖 Build footer line, with OUTDATED warning if isOutdated is true
-  let footerLine = ''
-  if (isOutdated) {
-    // 📖 Show OUTDATED in red background, high contrast warning
-    footerLine = chalk.bgRed.bold.white('  ⚠ OUTDATED version, please update with "npm i -g free-coding-models@latest"  ')
-  } else {
-    footerLine =
-      chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
-      chalk.dim('  •  ') +
-      '⭐ ' +
-      chalk.yellow('\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\Star on GitHub\x1b]8;;\x1b\\') +
-      chalk.dim('  •  ') +
-      '🤝 ' +
-      chalk.rgb(255, 165, 0)('\x1b]8;;https://github.com/vava-nessa/free-coding-models/graphs/contributors\x1b\\Contributors\x1b]8;;\x1b\\') +
-      chalk.dim('  •  ') +
-      '☕ ' +
-      chalk.rgb(255, 200, 100)('\x1b]8;;https://buymeacoffee.com/vavanessadev\x1b\\Buy me a coffee\x1b]8;;\x1b\\') +
-      chalk.dim('  •  ') +
-      '💬 ' +
-      chalk.rgb(200, 150, 255)('\x1b]8;;https://discord.gg/ZTNFHvvCkU\x1b\\Discord\x1b]8;;\x1b\\') +
-      chalk.dim(' → ') +
-      chalk.rgb(200, 150, 255)('https://discord.gg/ZTNFHvvCkU') +
-      chalk.dim('  •  ') +
-      chalk.yellow('N') + chalk.dim(' Changelog') +
-      chalk.dim('  •  ') +
-      chalk.dim('Ctrl+C Exit')
+  if (versionStatus.isOutdated) {
+    const outdatedMessage = `  ⚠ Update available: v${LOCAL_VERSION} -> v${versionStatus.latestVersion}. If auto-update did not complete, run: npm install -g free-coding-models@latest`
+    const paddedBanner = terminalCols > 0
+      ? outdatedMessage + ' '.repeat(Math.max(0, terminalCols - displayWidth(outdatedMessage)))
+      : outdatedMessage
+    // 📖 Reserve a dedicated full-width red row so the warning cannot blend into the footer links.
+    lines.push(chalk.bgRed.white.bold(paddedBanner))
   }
-  lines.push(footerLine)
 
   // 📖 Append \x1b[K (erase to EOL) to each line so leftover chars from previous
   // 📖 frames are cleared. Then pad with blank cleared lines to fill the terminal,