free-coding-models 0.5.86 → 0.5.88

package/src/core/security.js

@@ -17,21 +17,34 @@
  *    Now checkConfigSecurity() is async, awaited by the bin entry BEFORE the TUI
  *    starts, and it never prompts on non-TTY stdin or daemon/web/JSON surfaces.
  *
- * 📖 Secure permissions:
- *    - 0o600 (octal 600) = user:rw, group:---, world:---
- *    - Only the file owner can read or write
- *    - This is the standard for files containing secrets (SSH keys, API keys, etc.)
+ * 📖 Issue #173 follow-up (rutexd): on Windows the "fix" never persisted and the
+ *    warning re-fired on every launch. Root cause: Node maps win32 modes to only
+ *    0666 (writable) or 0444 (read-only), so 0600 is unreachable and
+ *    `(mode & 0o777) === 0o600` was always false; chmod 600 on win32 just clears
+ *    the read-only bit. The real fix:
+ *    - the Windows verdict now comes from the NTFS ACL via `icacls <file>`
+ *    - fixing on Windows runs `icacls /inheritance:r /grant:r <user>:F` and is
+ *      verified by re-reading the ACL before claiming success
+ *    - when the fix cannot be applied or verified, an ack marker file
+ *      (<config>.securityack) keeps the warning quiet for 30 days instead of
+ *      nagging on every launch (--fix-permissions bypasses the marker)
+ *    POSIX behaviour (chmod 600) is unchanged on macOS/Linux.
  *
- * 📖 Windows note: Node's chmod on win32 is best-effort (it can only toggle the
- *    read-only attribute, NTFS ACLs still govern real access). We still try,
- *    and the manual hint points at icacls for a real fix.
+ * 📖 Secure permissions:
+ *    - POSIX: 0o600 (octal 600) = user:rw, group:---, world:---
+ *    - Windows: NTFS inheritance disabled, grants only for the current user
+ *      (SYSTEM/Administrators whitelisted) - see parseIcaclsOutput in utils.js
  *
  * @functions
  *   → checkConfigSecurity() - Async main security check; awaited before the TUI starts
  *   → resolveSecurityAction() - Pure gate deciding auto-fix / prompt / warn-only (in utils.js)
+ *   → parseIcaclsOutput() - Pure parser for icacls output (in utils.js)
+ *   → shouldSkipSecurityWarn() - Pure anti-nag gate for repeat warnings (in utils.js)
  *   → getConfigPermissions() - Returns file mode object for config
- *   → isConfigSecure() - Boolean check if permissions are correct
- *   → fixConfigPermissions() - Applies chmod 600 to config file (best-effort on Windows)
+ *   → isConfigSecure() - Boolean check if permissions are correct (POSIX modes)
+ *   → fixConfigPermissions() - Applies chmod 600 to config file (POSIX)
+ *   → getWindowsAclStatus() - Async icacls read + parse → is the ACL secure?
+ *   → fixWindowsAcl() - Async icacls fix + ACL re-verify
  *   → promptSecurityFix() - Interactive prompt asking user to fix permissions
  *
  * @exports checkConfigSecurity, isConfigSecure, fixConfigPermissions, formatMode, formatModeRwx
@@ -41,8 +54,12 @@ import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import readline from 'node:readline'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
 import { CONFIG_PATH } from './config.js'
-import { resolveSecurityAction } from './utils.js'
+import { resolveSecurityAction, parseIcaclsOutput, shouldSkipSecurityWarn } from './utils.js'
+
+const execFileAsync = promisify(execFile)
 
 // 📖 Config file path - matches the path used in config.js (honours the
 // 📖 --config-dir / FCM_CONFIG_DIR override when set).
@@ -91,7 +108,8 @@ export function isConfigSecure() {
 }
 
 // 📖 Fix config file permissions to secure mode (chmod 600)
-// 📖 Best-effort on Windows (read-only bit); returns true if successful, false otherwise
+// 📖 POSIX path; on Windows this is NOT the real fix (see fixWindowsAcl) and is
+// 📖 kept only as a harmless last-ditch fallback. Returns true if successful.
 export function fixConfigPermissions() {
   const configPath = getConfigPath()
 
@@ -107,6 +125,88 @@ export function fixConfigPermissions() {
   }
 }
 
+// 📖 Current Windows user name, used both for icacls grants and for matching
+// 📖 ACE lines when parsing the ACL (os.userInfo works on win32 too).
+function getWindowsUserName() {
+  try {
+    return os.userInfo().username
+  } catch {
+    return process.env.USERNAME || ''
+  }
+}
+
+// 📖 Read the real NTFS ACL via icacls and decide if it is secure:
+// 📖 inheritance disabled + grants only for the current user (and trusted
+// 📖 SYSTEM/Administrators entries). Returns { checked, secure, ...parsed };
+// 📖 checked=false when icacls is missing or failed (caller falls back to the
+// 📖 ack-gated warning path instead of trusting useless mode bits).
+async function getWindowsAclStatus(configPath) {
+  try {
+    const { stdout } = await execFileAsync('icacls', [configPath], {
+      timeout: 5000,
+      windowsHide: true,
+    })
+    const parsed = parseIcaclsOutput({ output: stdout, userName: getWindowsUserName(), filePath: configPath })
+    const secure = !parsed.inheritanceEnabled && !parsed.othersHaveAccess && parsed.ownerHasAccess
+    return { checked: true, secure, ...parsed }
+  } catch (err) {
+    return { checked: false, secure: false, grants: [], otherNames: [] }
+  }
+}
+
+// 📖 Fix the NTFS ACL for real: drop inherited ACEs, grant only the current
+// 📖 user full control, then VERIFY by re-reading the ACL (never claim success
+// 📖 without proof - that lie was the core of the issue #173 follow-up).
+// 📖 execFile (no shell) keeps the path injection-safe even with spaces.
+async function fixWindowsAcl(configPath) {
+  const userName = getWindowsUserName()
+  if (!userName) return false
+
+  try {
+    await execFileAsync(
+      'icacls',
+      [configPath, '/inheritance:r', '/grant:r', `${userName}:F`],
+      { timeout: 5000, windowsHide: true }
+    )
+    const status = await getWindowsAclStatus(configPath)
+    return status.checked && status.secure
+  } catch (err) {
+    return false
+  }
+}
+
+// 📖 Anti-nag marker: written when we warned but could not fix/verify, so the
+// 📖 same warning does not re-fire on every launch (see shouldSkipSecurityWarn).
+// 📖 Lives next to the config so --config-dir / FCM_CONFIG_DIR stays coherent.
+function getAckPath() {
+  return `${getConfigPath()}.securityack`
+}
+
+function readSecurityAck() {
+  try {
+    return fs.readFileSync(getAckPath(), 'utf8').trim()
+  } catch {
+    return null
+  }
+}
+
+function writeSecurityAck() {
+  try {
+    fs.writeFileSync(getAckPath(), new Date().toISOString(), { mode: 0o600 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function clearSecurityAck() {
+  try {
+    fs.unlinkSync(getAckPath())
+  } catch {
+    // 📖 Nothing to clean up is fine.
+  }
+}
+
 // 📖 Format permission mode in octal (e.g., 0o644 → "644")
 // 📖 Exported for unit tests
 export function formatMode(mode) {
@@ -133,7 +233,9 @@ export function formatModeRwx(mode) {
 }
 
 // 📖 Print the insecure-permissions warning (stderr, so --json stdout stays clean)
-function printSecurityWarning(perms) {
+// 📖 On Windows, mode bits are meaningless (always 0666/0444), so when the ACL
+// 📖 was read we show WHAT actually grants access instead of a fake octal story.
+function printSecurityWarning(perms, aclStatus = { checked: false }) {
   const currentMode = formatMode(perms.mode)
   const currentRwx = formatModeRwx(perms.mode)
 
@@ -145,16 +247,29 @@ function printSecurityWarning(perms) {
   console.error('')
   console.error('This means other users on this system may be able to read your API keys.')
   console.error('')
-  console.error('Recommended: Fix permissions to 600 (rw-------) - owner read/write only')
+
+  if (aclStatus.checked) {
+    if (aclStatus.inheritanceEnabled) {
+      console.error('NTFS: this file inherits access permissions from your user folder.')
+    }
+    if (aclStatus.othersHaveAccess) {
+      const names = (aclStatus.otherNames || []).slice(0, 3).join(', ')
+      console.error(`NTFS: access is also granted to: ${names}`)
+    }
+    console.error('')
+  }
+
+  console.error('Recommended: restrict access to your user account only')
 }
 
-// 📖 Print the manual fix hint. On Windows, point at icacls since Node's chmod
-// 📖 only toggles the read-only attribute there.
+// 📖 Print the manual fix hint. Platform-matched command: icacls on Windows
+// 📖 (NTFS ACLs), chmod elsewhere.
 function printManualFixHint() {
   console.error('')
   if (IS_WINDOWS) {
+    const user = getWindowsUserName() || '$env:USERNAME'
     console.error('To fix manually (PowerShell), run:')
-    console.error(`  icacls "${getConfigPath()}" /inheritance:r /grant:r "$env:USERNAME:R,W"`)
+    console.error(`  icacls "${getConfigPath()}" /inheritance:r /grant:r "${user}:F"`)
   } else {
     console.error('To fix manually, run:')
     console.error(`  chmod 600 ${getConfigPath()}`)
@@ -164,24 +279,37 @@ function printManualFixHint() {
 
 // 📖 Apply the fix and report the outcome. Shared by the prompt path (user said
 // 📖 yes) and the auto-fix path (--fix-permissions / --yes / -y).
-function applyFixAndReport() {
-  const success = fixConfigPermissions()
+// 📖 Windows: icacls ACL fix, verified by re-reading the ACL.
+// 📖 POSIX: chmod 600, verified by re-statting the file.
+// 📖 If the fix cannot be verified, write the anti-nag ack so the warning does
+// 📖 not re-fire on every launch, and point at the manual command.
+async function applyFixAndReport() {
+  const configPath = getConfigPath()
+  let success = false
+
+  if (IS_WINDOWS) {
+    success = await fixWindowsAcl(configPath)
+  } else {
+    success = fixConfigPermissions() && getConfigPermissions()?.isSecure === true
+  }
 
   if (success) {
+    clearSecurityAck()
     console.error('')
     console.error('✅ Permissions fixed! Your API keys are now secure.')
     console.error('')
     if (IS_WINDOWS) {
-      console.error('Note: on Windows this is best-effort (read-only bit). See docs for NTFS ACLs.')
+      console.error(`NTFS access is now restricted to "${getWindowsUserName()}".`)
       console.error('')
     }
     return { wasSecure: false, wasFixed: true }
   }
 
+  writeSecurityAck()
   console.error('')
   console.error('❌ Failed to fix permissions automatically.')
   printManualFixHint()
-  return { wasSecure: false, wasFixed: false, error: 'chmod_failed' }
+  return { wasSecure: false, wasFixed: false, error: 'fix_failed' }
 }
 
 // 📖 Check security and handle the fix flow if needed
@@ -189,9 +317,14 @@ function applyFixAndReport() {
 // 📖 the confirmation prompt are visible and fully resolved before raw mode /
 // 📖 the alternate screen take over.
 //
+// 📖 Windows verdict (issue #173 follow-up): mode bits on win32 are only ever
+// 📖 0666 or 0444, so the POSIX 0600 check would nag forever. The real verdict
+// 📖 comes from the NTFS ACL (icacls). If icacls is unavailable, fall through to
+// 📖 the warning path but let the anti-nag ack keep it to once per 30 days.
+//
 // 📖 Options:
 //   autoFix       - true when --fix-permissions / --yes / -y was passed: apply the
-//                   fix without asking
+//                   fix without asking (also bypasses the anti-nag ack)
 //   promptAllowed - false on daemon/web/JSON surfaces: never prompt there, at most
 //                   warn on stderr
 //   stdinIsTTY    - override the stdin TTY detection (tests); defaults to real detection
@@ -205,11 +338,23 @@ export async function checkConfigSecurity(options = {}) {
     return { wasSecure: true, wasFixed: false }
   }
 
-  // 📖 Permissions are already secure
-  if (perms.isSecure) {
+  // 📖 Security verdict, platform-aware.
+  let aclStatus = { checked: false, secure: false, grants: [], otherNames: [] }
+  if (IS_WINDOWS) {
+    aclStatus = await getWindowsAclStatus(perms.path)
+    if (aclStatus.checked && aclStatus.secure) {
+      return { wasSecure: true, wasFixed: false }
+    }
+  } else if (perms.isSecure) {
     return { wasSecure: true, wasFixed: false }
   }
 
+  // 📖 Anti-nag gate: if we already warned recently and the fix did not stick,
+  // 📖 stay quiet instead of nagging on every launch. --fix-permissions bypasses.
+  if (options.autoFix !== true && shouldSkipSecurityWarn({ ackedAt: readSecurityAck() })) {
+    return { wasSecure: false, wasFixed: false, error: 'warned_recently' }
+  }
+
   // 📖 Pure gate (see utils.js): decides auto-fix vs prompt vs warn-only.
   const action = resolveSecurityAction({
     configExists: true,
@@ -225,7 +370,7 @@ export async function checkConfigSecurity(options = {}) {
 
   // 📖 Security issue detected! Print the warning first so it is on screen
   // 📖 no matter which path follows.
-  printSecurityWarning(perms)
+  printSecurityWarning(perms, aclStatus)
 
   if (action === 'auto-fix') {
     return applyFixAndReport()
@@ -234,6 +379,7 @@ export async function checkConfigSecurity(options = {}) {
   if (action === 'warn-only') {
     console.error('Running non-interactively (piped stdin or daemon/web mode), so skipping the prompt.')
     printManualFixHint()
+    writeSecurityAck()
     return { wasSecure: false, wasFixed: false, error: 'non_interactive' }
   }
 

package/src/core/shared-helpers.js

@@ -16,7 +16,7 @@
  *   → safeJsonParse — JSON.parse with fallback
  *   → maskApiKey — Mask API key for display (show last 4 chars)
  *
- * @exports sleep, ensureDir, readJson, writeJson, atomicWriteJson, safeJsonParse, maskApiKey
+ * @exports sleep, ensureDir, readJson, writeJson, atomicWriteJson, safeJsonParse, shellSingleQuote, maskApiKey
  */
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
@@ -94,6 +94,17 @@ export function safeJsonParse(raw, fallback = null) {
   }
 }
 
+/**
+ * 📖 Single-quote shell escaping for values interpolated into sourced env files.
+ * 📖 Wraps the value in single quotes and escapes embedded single quotes the
+ * 📖 POSIX way (`'` -> `'\''`) so quotes, `$`, and backticks stay literal.
+ * @param {string} value
+ * @returns {string}
+ */
+export function shellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
 /**
  * 📖 Mask an API key for display. Shows last 4 chars, rest as bullets.
  * @param {string} key

package/src/core/shell-env.js

@@ -35,7 +35,7 @@
  * @see src/provider-metadata.js — ENV_VAR_NAMES maps provider → env var name
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs'
+import { chmodSync, readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import * as readline from 'node:readline'
@@ -191,6 +191,8 @@ export function syncShellEnv(config) {
   try {
     const content = buildEnvContent(config, shell)
     writeFileSync(envPath, content, { mode: 0o600 })
+    // 📖 chmod also tightens pre-existing files created before the mode option was added.
+    chmodSync(envPath, 0o600)
     return { success: true, envPath }
   } catch (err) {
     return { success: false, envPath, error: err.message }

package/src/core/telemetry.js

@@ -10,7 +10,7 @@
  *   - PostHog is used for product analytics (`app_start`, `app_use`, and lightweight
  *     `app_action` events covering launches and key product actions).
  *   - Discord webhooks carry anonymous feature requests (J key) and bug reports (I key).
- *   - `isTelemetryEnabled()` checks: CLI flag → env var → default (enabled).
+ *   - `isTelemetryEnabled()` checks: CLI flag → env var → config opt-out → default (enabled).
  *   - `telemetryDebug()` writes to stderr only when FREE_CODING_MODELS_TELEMETRY_DEBUG=1.
  *   - `sendUsageTelemetry()` has a hard 1.2 s timeout so it never blocks startup.
  *
@@ -20,6 +20,8 @@
  *   - FREE_CODING_MODELS_POSTHOG_KEY             — override the PostHog project key
  *   - FREE_CODING_MODELS_POSTHOG_HOST            — override the PostHog host
  *   - POSTHOG_PROJECT_API_KEY / POSTHOG_HOST     — standard PostHog env vars (fallback)
+ *   - FCM_DISCORD_FEATURE_WEBHOOK                - feature request webhook URL
+ *   - FCM_DISCORD_BUG_WEBHOOK                    - bug report webhook URL
  *
  * @functions
  *   → parseTelemetryEnv(value)                    — Convert env string to boolean or null
@@ -63,12 +65,15 @@ const POSTHOG_PROJECT_KEY_DEFAULT = 'phc_5P1n8HaLof6nHM0tKJYt4bV5pj2XPb272fLVigw
 const POSTHOG_HOST_DEFAULT       = 'https://eu.i.posthog.com'
 
 // 📖 Discord feature request webhook configuration (anonymous feedback system).
-const DISCORD_WEBHOOK_URL   = 'https://discord.com/api/webhooks/1476709155992764427/hmnHNtpducvi5LClhv8DynENjUmmg9q8HI1Bx1lNix56UHqrqZf55rW95LGvNJ2W4j7D'
+// 📖 FCM_DISCORD_FEATURE_WEBHOOK: env var holding the feature-request webhook URL.
+// 📖 When unset, the feature request action reports "not configured" instead of posting.
+const DISCORD_WEBHOOK_URL   = (process.env.FCM_DISCORD_FEATURE_WEBHOOK || '').trim()
 const DISCORD_BOT_NAME      = 'TUI - Feature Requests'
 const DISCORD_EMBED_COLOR   = 0x39FF14  // Vert fluo (RGB: 57, 255, 20)
 
 // 📖 Discord bug report webhook configuration (anonymous bug reports).
-const DISCORD_BUG_WEBHOOK_URL  = 'https://discord.com/api/webhooks/1476715954409963743/5cOLf7U_891f1jwxRBLIp2RIP9xYhr4rWtOhipzKKwVdFVl1Bj89X_fB6I_uGXZiGT9E'
+// 📖 FCM_DISCORD_BUG_WEBHOOK: env var holding the bug report webhook URL.
+const DISCORD_BUG_WEBHOOK_URL  = (process.env.FCM_DISCORD_BUG_WEBHOOK || '').trim()
 const DISCORD_BUG_BOT_NAME     = 'TUI Bug Report'
 const DISCORD_BUG_EMBED_COLOR  = 0xFF5733  // Rouge (RGB: 255, 87, 51)
 
@@ -194,7 +199,7 @@ export function getTelemetryTerminal() {
 
 /**
  * 📖 Resolve telemetry effective state with clear precedence:
- * 📖 CLI flag > env var > enabled by default (forced for all users).
+ * 📖 CLI flag > env var > config opt-out > enabled by default.
  * @param {Record<string, unknown>} config
  * @param {{ noTelemetry?: boolean }} cliArgs
  * @returns {boolean}
@@ -204,7 +209,9 @@ export function isTelemetryEnabled(config, cliArgs) {
   const envTelemetry = parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY)
   if (envTelemetry !== null) return envTelemetry
   ensureTelemetryConfig(config)
-  return true
+  // 📖 Honor a persisted opt-out (config telemetry.enabled=false) set from the UI;
+  // 📖 CLI flags and FREE_CODING_MODELS_TELEMETRY still override it above.
+  return config.telemetry.enabled !== false
 }
 
 /**
@@ -314,6 +321,9 @@ export async function sendUsageTelemetry(config, cliArgs, payload) {
  * @returns {Promise<{ success: boolean, error: string|null }>}
  */
 export async function sendFeatureRequest(message) {
+  if (!DISCORD_WEBHOOK_URL) {
+    return { success: false, error: 'feedback webhook not configured (set FCM_DISCORD_FEATURE_WEBHOOK)' }
+  }
   try {
     // 📖 Collect anonymous telemetry for context (no personal data)
     const system = getTelemetrySystem()
@@ -361,6 +371,9 @@ export async function sendFeatureRequest(message) {
  * @returns {Promise<{ success: boolean, error: string|null }>}
  */
 export async function sendBugReport(message) {
+  if (!DISCORD_BUG_WEBHOOK_URL) {
+    return { success: false, error: 'feedback webhook not configured (set FCM_DISCORD_BUG_WEBHOOK)' }
+  }
   try {
     // 📖 Collect anonymous telemetry for context (no personal data)
     const system = getTelemetrySystem()

package/src/core/tool-launchers.js

@@ -48,7 +48,7 @@ import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta, TOOL_METADATA } from './tool-metadata.js'
 import { PROVIDER_METADATA } from './provider-metadata.js'
 import { resolveToolBinaryPath } from './tool-bootstrap.js'
-import { ensureDir, readJson, writeJson } from './shared-helpers.js'
+import { ensureDir, readJson, writeJson, shellSingleQuote } from './shared-helpers.js'
 import { parseContextWindow } from './endpoint-installer.js'
 import { resolveCloudflareUrl } from './ping.js'
 
@@ -70,9 +70,11 @@ function parseCtxToTokens(ctx) {
   if (!match) return null
   const num = parseFloat(match[1])
   const suffix = match[2].toLowerCase()
-  // 📖 LLM token counts use binary (1024), not decimal (1000).
-  if (suffix === 'k') return Math.round(num * 1024)
-  if (suffix === 'm') return Math.round(num * 1024 * 1024)
+  // 📖 Catalog ctx strings use DECIMAL semantics ("1M" = 1,000,000), matching
+  // 📖 parseContextWindow in endpoint-installer.js. The old 1024 multipliers made
+  // 📖 the two parsers disagree (1048576 vs 1000000) for the same catalog value.
+  if (suffix === 'k') return Math.round(num * 1000)
+  if (suffix === 'm') return Math.round(num * 1000 * 1000)
   return Math.round(num)
 }
 
@@ -414,10 +416,11 @@ function writeOpenHandsEnv(model, apiKey, baseUrl, paths = getDefaultToolPaths()
   const backupPath = backupIfExists(filePath)
   const lines = [
     '# 📖 Managed by free-coding-models',
-    `export OPENAI_API_KEY="${apiKey}"`,
+    // 📖 Single-quote the key so quotes/$()/backticks in it stay literal on `source`.
+    `export OPENAI_API_KEY=${shellSingleQuote(apiKey)}`,
     `export OPENAI_BASE_URL="${baseUrl}"`,
     `export OPENAI_MODEL="${model.modelId}"`,
-    `export LLM_API_KEY="${apiKey}"`,
+    `export LLM_API_KEY=${shellSingleQuote(apiKey)}`,
     `export LLM_BASE_URL="${baseUrl}"`,
     `export LLM_MODEL="openai/${model.modelId}"`,
   ]

package/src/core/updater.js

@@ -31,6 +31,7 @@
  *   → resolveCurrentNpmInstallTarget()   — Detect the npm prefix that owns the active package
  *   → getInstallArgs(pm, version)        — Build correct { bin, args } per package manager
  *   → getManualInstallCmd(pm, version)   — Human-readable install command string for error messages
+ *   → isNewerVersion(remote, local)      - Semver compare: true only when remote is greater
  *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
  *   → checkForUpdate()                   — Startup wrapper, returns version string or null
  *   → isPackageDevMode()                 — Detect git/dev checkouts that must not self-update
@@ -38,7 +39,7 @@
  *   → runUpdate(latestVersion)           — Install new version via detected PM + relaunch
  * @exports
  *   detectPackageManager, resolveCurrentNpmInstallTarget, getInstallArgs, getManualInstallCmd,
- *   checkForUpdateDetailed, checkForUpdate, isPackageDevMode,
+ *   isNewerVersion, checkForUpdateDetailed, checkForUpdate, isPackageDevMode,
  *   enforceMandatoryStartupUpdate, runUpdate, fetchLastReleaseDate
  *
  * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
@@ -232,6 +233,31 @@ export function getManualInstallCmd(pm, version, options = {}) {
   return [bin, ...args].map(shellQuoteArg).join(' ')
 }
 
+/**
+ * 📖 isNewerVersion: dependency-free semver comparison of dotted numeric versions.
+ * 📖 Update availability used to be a string inequality, so a dist-tag rollback
+ * 📖 (remote < local) triggered a pointless "downgrade" install. Only a strictly
+ * 📖 GREATER remote version counts as an update now.
+ * @param {string} remoteVersion
+ * @param {string} localVersion
+ * @returns {boolean} true only when remoteVersion > localVersion
+ */
+export function isNewerVersion(remoteVersion, localVersion) {
+  const parseParts = (v) => String(v ?? '')
+    .trim()
+    .replace(/^v/i, '')
+    .split('.')
+    .map(part => parseInt(part, 10) || 0)
+  const remote = parseParts(remoteVersion)
+  const local = parseParts(localVersion)
+  const len = Math.max(remote.length, local.length)
+  for (let i = 0; i < len; i++) {
+    const diff = (remote[i] || 0) - (local[i] || 0)
+    if (diff !== 0) return diff > 0
+  }
+  return false
+}
+
 /**
  * 📖 checkForUpdateDetailed: Fetch npm latest version with explicit error details.
  * 📖 Used by settings manual-check flow to display meaningful status in the UI.
@@ -242,7 +268,7 @@ export async function checkForUpdateDetailed() {
     const res = await fetch('https://registry.npmjs.org/free-coding-models/latest', { signal: AbortSignal.timeout(5000) })
     if (!res.ok) return { latestVersion: null, error: `HTTP ${res.status}` }
     const data = await res.json()
-    if (data.version && data.version !== LOCAL_VERSION) return { latestVersion: data.version, error: null }
+    if (data.version && isNewerVersion(data.version, LOCAL_VERSION)) return { latestVersion: data.version, error: null }
     return { latestVersion: null, error: null }
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Unknown error'