diff --git a/src/main/lib/agentRuntime/backgroundExecSessionManager.ts b/src/main/lib/agentRuntime/backgroundExecSessionManager.ts
index dc3c99227..93d3c8db7 100644
--- a/src/main/lib/agentRuntime/backgroundExecSessionManager.ts
+++ b/src/main/lib/agentRuntime/backgroundExecSessionManager.ts
@@ -3,7 +3,7 @@ import fs from 'fs'
 import path from 'path'
 import { nanoid } from 'nanoid'
 import logger from '@shared/logger'
-import { getShellEnvironment, getUserShell } from './shellEnvHelper'
+import { getUserShell } from './shellEnvHelper'
 import { terminateProcessTree } from './processTree'
 import { resolveSessionDir } from './sessionPaths'
 
@@ -121,7 +121,6 @@ export class BackgroundExecSessionManager {
     const config = getConfig()
     const sessionId = `bg_${nanoid(12)}`
     const { shell, args } = getUserShell()
-    const shellEnv = await getShellEnvironment()
 
     const sessionDir = resolveSessionDir(conversationId)
     if (sessionDir) {
@@ -134,11 +133,7 @@ export class BackgroundExecSessionManager {
 
     const child = spawn(shell, [...args, command], {
       cwd,
-      env: {
-        ...process.env,
-        ...shellEnv,
-        ...options?.env
-      },
+      env: { ...process.env, ...(options?.env ?? {}) },
       detached: process.platform !== 'win32',
       stdio: ['pipe', 'pipe', 'pipe']
     })
diff --git a/src/main/lib/agentRuntime/rtkRuntimeService.ts b/src/main/lib/agentRuntime/rtkRuntimeService.ts
index 6dab3badf..26cd190c1 100644
--- a/src/main/lib/agentRuntime/rtkRuntimeService.ts
+++ b/src/main/lib/agentRuntime/rtkRuntimeService.ts
@@ -12,7 +12,7 @@ import type {
   UsageDashboardRtkSummary
 } from '@shared/types/agent-interface'
 import logger from '@shared/logger'
-import { getShellEnvironment } from './shellEnvHelper'
+import { getShellEnvironment, mergeCommandEnvironment } from './shellEnvHelper'
 import { RuntimeHelper } from '../runtimeHelper'
 
 const RTK_ENABLED_SETTING_KEY = 'rtkEnabled'
@@ -650,15 +650,12 @@ export class RtkRuntimeService {
     dbPath?: string
   ): Promise<Record<string, string>> {
     const shellEnv = await this.getShellEnvironmentImpl()
-    const env = this.runtimeHelper.prependBundledRuntimeToEnv({
-      ...Object.fromEntries(
-        Object.entries(process.env).filter(
-          (entry): entry is [string, string] => typeof entry[1] === 'string'
-        )
-      ),
-      ...shellEnv,
-      ...baseEnv
-    })
+    const env = this.runtimeHelper.prependBundledRuntimeToEnv(
+      mergeCommandEnvironment({
+        shellEnv,
+        overrides: baseEnv
+      })
+    )
 
     if (dbPath) {
       fs.mkdirSync(path.dirname(dbPath), { recursive: true })
diff --git a/src/main/lib/agentRuntime/shellEnvHelper.ts b/src/main/lib/agentRuntime/shellEnvHelper.ts
index a8a502a25..9f075450f 100644
--- a/src/main/lib/agentRuntime/shellEnvHelper.ts
+++ b/src/main/lib/agentRuntime/shellEnvHelper.ts
@@ -1,19 +1,265 @@
 import { spawn } from 'child_process'
+import { app } from 'electron'
 import * as path from 'path'
+import { RuntimeHelper } from '../runtimeHelper'
+
+const runtimeHelper = RuntimeHelper.getInstance()
+
+const PATH_ENV_KEYS = ['PATH', 'Path', 'path'] as const
+const NODE_ENV_KEYS = [
+  'NVM_DIR',
+  'NVM_CD_FLAGS',
+  'NVM_BIN',
+  'NODE_PATH',
+  'NODE_VERSION',
+  'FNM_DIR',
+  'VOLTA_HOME',
+  'N_PREFIX'
+] as const
+const NPM_ENV_KEYS = [
+  'npm_config_registry',
+  'npm_config_cache',
+  'npm_config_prefix',
+  'npm_config_tmp',
+  'NPM_CONFIG_REGISTRY',
+  'NPM_CONFIG_CACHE',
+  'NPM_CONFIG_PREFIX',
+  'NPM_CONFIG_TMP'
+] as const
+const RELEVANT_ENV_KEYS = [...PATH_ENV_KEYS, ...NODE_ENV_KEYS, ...NPM_ENV_KEYS] as const
 
-// Memory cache for shell environment variables
 let cachedShellEnv: Record<string, string> | null = null
 
-const TIMEOUT_MS = 3000 // 3 seconds timeout
+const TIMEOUT_MS = 8000
+
+function getPathSeparator(): string {
+  return process.platform === 'win32' ? ';' : ':'
+}
+
+function getPrimaryPathKey(): 'PATH' | 'Path' {
+  return process.platform === 'win32' ? 'Path' : 'PATH'
+}
+
+function toStringEnvEntries(
+  input: NodeJS.ProcessEnv | Record<string, string> | undefined
+): Record<string, string> {
+  if (!input) {
+    return {}
+  }
+
+  return Object.fromEntries(
+    Object.entries(input).filter((entry): entry is [string, string] => typeof entry[1] === 'string')
+  )
+}
+
+function pickRelevantEnvironment(
+  input: NodeJS.ProcessEnv | Record<string, string> | undefined
+): Record<string, string> {
+  const env = toStringEnvEntries(input)
+  const filtered: Record<string, string> = {}
+
+  for (const key of RELEVANT_ENV_KEYS) {
+    const value = env[key]
+    if (typeof value === 'string' && value !== '') {
+      filtered[key] = value
+    }
+  }
+
+  return filtered
+}
+
+function getDefaultPathEntries(): string[] {
+  try {
+    return runtimeHelper.getDefaultPaths(app.getPath('home'))
+  } catch {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || ''
+    return homeDir ? runtimeHelper.getDefaultPaths(homeDir) : []
+  }
+}
+
+export function getPathEntriesFromEnv(
+  input: NodeJS.ProcessEnv | Record<string, string> | undefined
+): string[] {
+  const env = toStringEnvEntries(input)
+  const separator = getPathSeparator()
+  const entries: string[] = []
+
+  for (const key of PATH_ENV_KEYS) {
+    const value = env[key]
+    if (typeof value !== 'string' || value.length === 0) {
+      continue
+    }
+    entries.push(...value.split(separator))
+  }
+
+  return entries.map((entry) => entry.trim()).filter((entry) => entry.length > 0)
+}
+
+export function mergePathEntries(
+  pathSources: Array<string | string[] | null | undefined>,
+  options: {
+    includeDefaultPaths?: boolean
+    defaultPaths?: string[]
+  } = {}
+): { key: 'PATH' | 'Path'; value: string; entries: string[] } {
+  const entries: string[] = []
+  const separator = getPathSeparator()
+  const includeDefaultPaths = options.includeDefaultPaths !== false
+
+  for (const source of pathSources) {
+    if (!source) {
+      continue
+    }
+
+    if (Array.isArray(source)) {
+      entries.push(...source)
+      continue
+    }
+
+    entries.push(...source.split(separator))
+  }
+
+  if (includeDefaultPaths) {
+    entries.push(...(options.defaultPaths ?? getDefaultPathEntries()))
+  }
+
+  const seen = new Set<string>()
+  const deduped = entries
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .filter((entry) => {
+      const normalized = process.platform === 'win32' ? entry.toLowerCase() : entry
+      if (seen.has(normalized)) {
+        return false
+      }
+      seen.add(normalized)
+      return true
+    })
+
+  return {
+    key: getPrimaryPathKey(),
+    value: deduped.join(separator),
+    entries: deduped
+  }
+}
+
+export function setPathEntriesOnEnv(
+  env: Record<string, string>,
+  pathSources: Array<string | string[] | null | undefined>,
+  options: {
+    includeDefaultPaths?: boolean
+    defaultPaths?: string[]
+  } = {}
+): Record<string, string> {
+  const normalized = mergePathEntries(pathSources, options)
+
+  delete env.PATH
+  delete env.Path
+  delete env.path
+
+  if (normalized.value.length > 0) {
+    env[normalized.key] = normalized.value
+    if (process.platform === 'win32') {
+      env.PATH = normalized.value
+      env.Path = normalized.value
+    }
+  }
+
+  return env
+}
+
+export function mergeCommandEnvironment(
+  options: {
+    processEnv?: NodeJS.ProcessEnv | Record<string, string>
+    shellEnv?: Record<string, string>
+    overrides?: Record<string, string>
+    prependPathSources?: Array<string | string[] | null | undefined>
+    includeDefaultPaths?: boolean
+  } = {}
+): Record<string, string> {
+  const processEnv = toStringEnvEntries(options.processEnv ?? process.env)
+  const shellEnv = pickRelevantEnvironment(options.shellEnv)
+  const overrides = toStringEnvEntries(options.overrides)
+  const env: Record<string, string> = {
+    ...processEnv,
+    ...shellEnv
+  }
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (PATH_ENV_KEYS.includes(key as (typeof PATH_ENV_KEYS)[number])) {
+      continue
+    }
+    env[key] = value
+  }
+
+  setPathEntriesOnEnv(
+    env,
+    [
+      ...(options.prependPathSources ?? []),
+      getPathEntriesFromEnv(overrides),
+      getPathEntriesFromEnv(shellEnv),
+      getPathEntriesFromEnv(processEnv)
+    ],
+    {
+      includeDefaultPaths: options.includeDefaultPaths
+    }
+  )
+
+  return env
+}
+
+function getShellBootstrapMarkers() {
+  const suffix = `${process.pid}_${Date.now().toString(36)}`
+  return {
+    start: `__DEEPCHAT_SHELL_ENV_START_${suffix}__`,
+    end: `__DEEPCHAT_SHELL_ENV_END_${suffix}__`
+  }
+}
+
+function buildShellBootstrapCommand(startMarker: string, endMarker: string): string {
+  return `printf '%s\\n' '${startMarker}'; env; printf '%s\\n' '${endMarker}'`
+}
+
+function parseShellBootstrapOutput(output: string, startMarker: string, endMarker: string) {
+  const lines = output.split(/\r?\n/)
+  const startIndex = lines.findIndex((line) => line.trim() === startMarker)
+  const endIndex = lines.findIndex((line, index) => index > startIndex && line.trim() === endMarker)
+
+  if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+    throw new Error('Missing shell environment markers in bootstrap output')
+  }
+
+  const env: Record<string, string> = {}
+  for (const line of lines.slice(startIndex + 1, endIndex)) {
+    const separatorIndex = line.indexOf('=')
+    if (separatorIndex <= 0) {
+      continue
+    }
+
+    const key = line.slice(0, separatorIndex).trim()
+    const value = line.slice(separatorIndex + 1).trim()
+    if (key.length > 0) {
+      env[key] = value
+    }
+  }
+
+  return env
+}
+
+function getShellBootstrapArgs(shellPath: string, command: string): string[] {
+  const shellName = path.basename(shellPath).toLowerCase()
+
+  if (shellName.includes('fish') || shellName.includes('zsh') || shellName.includes('bash')) {
+    return ['-l', '-i', '-c', command]
+  }
+
+  return ['-l', '-c', command]
+}
 
-/**
- * Get user's default shell
- */
 export function getUserShell(): { shell: string; args: string[] } {
   const platform = process.platform
 
   if (platform === 'win32') {
-    // Windows: use PowerShell or cmd.exe
     const powershell = process.env.PSModulePath ? 'powershell.exe' : null
     if (powershell) {
       return { shell: powershell, args: ['-NoProfile', '-Command'] }
@@ -21,56 +267,30 @@ export function getUserShell(): { shell: string; args: string[] } {
     return { shell: 'cmd.exe', args: ['/c'] }
   }
 
-  // Unix-like: use SHELL env var or default to bash
-  const shell = process.env.SHELL || '/bin/bash'
-  if (shell.includes('bash')) {
-    return { shell, args: ['-c'] }
-  }
-  if (shell.includes('zsh')) {
-    return { shell, args: ['-c'] }
-  }
-  if (shell.includes('fish')) {
-    return { shell, args: ['-c'] }
-  }
+  const fallbackShell =
+    platform === 'darwin' ? '/bin/zsh' : platform === 'linux' ? '/bin/bash' : '/bin/sh'
+  const shell = process.env.SHELL || fallbackShell
+
   return { shell, args: ['-c'] }
 }
 
-/**
- * Execute shell command to get environment variables
- * This will source shell initialization files to get nvm/n/fnm/volta paths
- */
-async function executeShellEnvCommand(): Promise<Record<string, string>> {
-  const { shell, args } = getUserShell()
-  const platform = process.platform
-
-  let envCommand: string
-
-  if (platform === 'win32') {
-    envCommand = 'Get-ChildItem Env: | ForEach-Object { "$($_.Name)=$($_.Value)" }'
-  } else {
-    const shellName = path.basename(shell)
-
-    if (shellName === 'bash') {
-      envCommand = `
-        [ -f ~/.bashrc ] && source ~/.bashrc
-        [ -f ~/.bash_profile ] && source ~/.bash_profile
-        [ -f ~/.profile ] && source ~/.profile
-        env
-      `.trim()
-    } else if (shellName === 'zsh') {
-      envCommand = `
-        [ -f ~/.zshrc ] && source ~/.zshrc
-        env
-      `.trim()
-    } else {
-      envCommand = 'env'
-    }
+export async function resolveShellBootstrapEnv(): Promise<Record<string, string>> {
+  if (process.platform === 'win32') {
+    return pickRelevantEnvironment(process.env)
   }
 
+  const { shell } = getUserShell()
+  const { start, end } = getShellBootstrapMarkers()
+  const envCommand = buildShellBootstrapCommand(start, end)
+  const args = getShellBootstrapArgs(shell, envCommand)
+
   return await new Promise<Record<string, string>>((resolve, reject) => {
-    const child = spawn(shell, [...args, envCommand], {
+    const child = spawn(shell, args, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env }
+      env: {
+        ...process.env,
+        TERM: process.env.TERM || 'dumb'
+      }
     })
 
     let stdout = ''
@@ -82,55 +302,64 @@ async function executeShellEnvCommand(): Promise<Record<string, string>> {
       reject(new Error(`Shell environment command timed out after ${TIMEOUT_MS}ms`))
     }, TIMEOUT_MS)
 
-    child.stdout?.on('data', (data: Buffer) => {
+    child.stdout?.on('data', (data: Buffer | string) => {
       stdout += data.toString()
     })
 
-    child.stderr?.on('data', (data: Buffer) => {
+    child.stderr?.on('data', (data: Buffer | string) => {
       stderr += data.toString()
     })
 
     child.on('error', (error) => {
-      if (timeoutId) clearTimeout(timeoutId)
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
       reject(error)
     })
 
     child.on('exit', (code, signal) => {
-      if (timeoutId) clearTimeout(timeoutId)
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
 
       if (code !== 0 && signal === null) {
-        console.warn(
-          `[ACP] Shell environment command exited with code ${code}, stderr: ${stderr.substring(0, 200)}`
+        reject(
+          new Error(
+            `Shell environment command exited with code ${code}, stderr: ${stderr.substring(0, 200)}`
+          )
         )
-        resolve({})
         return
       }
 
       if (signal) {
-        console.warn(`[ACP] Shell environment command killed by signal: ${signal}`)
-        resolve({})
+        reject(new Error(`Shell environment command killed by signal: ${signal}`))
         return
       }
 
-      const env: Record<string, string> = {}
-      const lines = stdout.split('\n').filter((line) => line.trim().length > 0)
-      for (const line of lines) {
-        const match = line.match(/^([^=]+)=(.*)$/)
-        if (match) {
-          const [, key, value] = match
-          env[key.trim()] = value.trim()
-        }
-      }
-
-      resolve(env)
+      resolve(parseShellBootstrapOutput(stdout, start, end))
     })
   })
 }
 
-/**
- * Get shell environment variables with caching
- * This will source shell initialization files to get nvm/n/fnm/volta paths
- */
+function normalizeShellEnvironment(
+  shellBootstrapEnv: Record<string, string>,
+  processEnv: NodeJS.ProcessEnv | Record<string, string> = process.env
+): Record<string, string> {
+  const processRelevantEnv = pickRelevantEnvironment(processEnv)
+  const shellRelevantEnv = pickRelevantEnvironment(shellBootstrapEnv)
+  const merged: Record<string, string> = {
+    ...processRelevantEnv,
+    ...shellRelevantEnv
+  }
+
+  setPathEntriesOnEnv(merged, [
+    getPathEntriesFromEnv(shellRelevantEnv),
+    getPathEntriesFromEnv(processRelevantEnv)
+  ])
+
+  return merged
+}
+
 export async function getShellEnvironment(): Promise<Record<string, string>> {
   if (cachedShellEnv !== null) {
     console.log('[ACP] Using cached shell environment variables')
@@ -140,73 +369,27 @@ export async function getShellEnvironment(): Promise<Record<string, string>> {
   console.log('[ACP] Fetching shell environment variables (this may take a moment)...')
 
   try {
-    const shellEnv = await executeShellEnvCommand()
-    const filteredEnv: Record<string, string> = {}
-
-    if (shellEnv.PATH) {
-      filteredEnv.PATH = shellEnv.PATH
-    }
-    if (shellEnv.Path) {
-      filteredEnv.Path = shellEnv.Path
-    }
-
-    const nodeEnvVars = [
-      'NVM_DIR',
-      'NVM_CD_FLAGS',
-      'NVM_BIN',
-      'NODE_PATH',
-      'NODE_VERSION',
-      'FNM_DIR',
-      'VOLTA_HOME',
-      'N_PREFIX'
-    ]
-
-    for (const key of nodeEnvVars) {
-      if (shellEnv[key]) {
-        filteredEnv[key] = shellEnv[key]
-      }
-    }
-
-    const npmEnvVars = [
-      'npm_config_registry',
-      'npm_config_cache',
-      'npm_config_prefix',
-      'npm_config_tmp',
-      'NPM_CONFIG_REGISTRY',
-      'NPM_CONFIG_CACHE',
-      'NPM_CONFIG_PREFIX',
-      'NPM_CONFIG_TMP'
-    ]
-
-    for (const key of npmEnvVars) {
-      if (shellEnv[key]) {
-        filteredEnv[key] = shellEnv[key]
-      }
-    }
+    const shellEnv = await resolveShellBootstrapEnv()
+    const normalizedEnv = normalizeShellEnvironment(shellEnv)
 
-    cachedShellEnv = filteredEnv
+    cachedShellEnv = normalizedEnv
 
     console.log('[ACP] Shell environment variables fetched and cached:', {
-      pathLength: filteredEnv.PATH?.length || filteredEnv.Path?.length || 0,
-      hasNvm: !!filteredEnv.NVM_DIR,
-      hasFnm: !!filteredEnv.FNM_DIR,
-      hasVolta: !!filteredEnv.VOLTA_HOME,
-      hasN: !!filteredEnv.N_PREFIX,
-      envVarCount: Object.keys(filteredEnv).length
+      pathLength: normalizedEnv.PATH?.length || normalizedEnv.Path?.length || 0,
+      hasNvm: !!normalizedEnv.NVM_DIR,
+      hasFnm: !!normalizedEnv.FNM_DIR,
+      hasVolta: !!normalizedEnv.VOLTA_HOME,
+      hasN: !!normalizedEnv.N_PREFIX,
+      envVarCount: Object.keys(normalizedEnv).length
     })
 
-    return filteredEnv
+    return normalizedEnv
   } catch (error) {
     console.warn('[ACP] Failed to get shell environment variables:', error)
-    cachedShellEnv = {}
-    return {}
+    return normalizeShellEnvironment(toStringEnvEntries(process.env), process.env)
   }
 }
 
-/**
- * Clear the shell environment cache
- * Should be called when ACP configuration changes (e.g., useBuiltinRuntime)
- */
 export function clearShellEnvironmentCache(): void {
   cachedShellEnv = null
   console.log('[ACP] Shell environment cache cleared')
diff --git a/src/main/presenter/configPresenter/acpInitHelper.ts b/src/main/presenter/configPresenter/acpInitHelper.ts
index 0128e3bc7..53ac75170 100644
--- a/src/main/presenter/configPresenter/acpInitHelper.ts
+++ b/src/main/presenter/configPresenter/acpInitHelper.ts
@@ -7,7 +7,12 @@ import type { AcpBuiltinAgentId, AcpAgentConfig, AcpAgentProfile } from '@shared
 import { spawn } from 'node-pty'
 import type { IPty } from 'node-pty'
 import { RuntimeHelper } from '@/lib/runtimeHelper'
-import { getShellEnvironment } from '@/lib/agentRuntime/shellEnvHelper'
+import {
+  getPathEntriesFromEnv,
+  getShellEnvironment,
+  mergeCommandEnvironment,
+  setPathEntriesOnEnv
+} from '@/lib/agentRuntime/shellEnvHelper'
 
 const execAsync = promisify(exec)
 
@@ -507,84 +512,48 @@ class AcpInitHelper {
       hasProfileEnv: !!(profile.env && Object.keys(profile.env).length > 0)
     })
 
-    const env: Record<string, string> = {}
-
-    // Add system environment variables
-    const systemEnvCount = Object.entries(process.env).filter(
-      ([, value]) => value !== undefined && value !== ''
-    ).length
-    Object.entries(process.env).forEach(([key, value]) => {
-      if (value !== undefined && value !== '') {
-        env[key] = value
-      }
-    })
+    let env = mergeCommandEnvironment()
+    const systemEnvCount = Object.keys(env).length
     console.log('[ACP Init] Added system environment variables:', systemEnvCount)
 
-    // Merge shell environment (includes user PATH from shell startup)
-    const pathKeys = ['PATH', 'Path', 'path']
-    const existingPaths: string[] = []
-    pathKeys.forEach((key) => {
-      const value = env[key]
-      if (value) existingPaths.push(value)
-    })
-
     try {
       const shellEnv = await getShellEnvironment()
-      Object.entries(shellEnv).forEach(([key, value]) => {
-        if (value !== undefined && value !== '' && !pathKeys.includes(key)) {
-          env[key] = value
-        }
-      })
-      const shellPath = shellEnv.PATH || shellEnv.Path || shellEnv.path
-      if (shellPath) {
-        existingPaths.unshift(shellPath)
-      }
+      env = mergeCommandEnvironment({ shellEnv })
     } catch (error) {
       console.warn('[ACP Init] Failed to merge shell environment variables:', error)
     }
 
-    // Prepare PATH merging
-    const HOME_DIR = app.getPath('home')
-    const defaultPaths = this.runtimeHelper.getDefaultPaths(HOME_DIR)
-    const allPaths = [...existingPaths, ...defaultPaths]
+    const prependPathSources: string[] = []
 
-    // Add runtime paths to PATH if using builtin runtime
     if (useBuiltinRuntime) {
-      const runtimePaths: string[] = []
-
       const uvRuntimePath = this.runtimeHelper.getUvRuntimePath()
       const nodeRuntimePath = this.runtimeHelper.getNodeRuntimePath()
 
       if (uvRuntimePath) {
-        runtimePaths.push(uvRuntimePath)
+        prependPathSources.push(uvRuntimePath)
         console.log('[ACP Init] Added UV runtime path:', uvRuntimePath)
       }
 
       if (process.platform === 'win32') {
         if (nodeRuntimePath) {
-          runtimePaths.push(nodeRuntimePath)
+          prependPathSources.push(nodeRuntimePath)
           console.log('[ACP Init] Added Node runtime path (Windows):', nodeRuntimePath)
         }
-      } else {
-        if (nodeRuntimePath) {
-          const nodeBinPath = path.join(nodeRuntimePath, 'bin')
-          runtimePaths.push(nodeBinPath)
-          console.log('[ACP Init] Added Node runtime path (Unix):', nodeBinPath)
-        }
+      } else if (nodeRuntimePath) {
+        const nodeBinPath = path.join(nodeRuntimePath, 'bin')
+        prependPathSources.push(nodeBinPath)
+        console.log('[ACP Init] Added Node runtime path (Unix):', nodeBinPath)
       }
 
-      if (runtimePaths.length > 0) {
-        allPaths.unshift(...runtimePaths)
+      if (prependPathSources.length > 0) {
+        setPathEntriesOnEnv(env, [prependPathSources, getPathEntriesFromEnv(env)], {
+          includeDefaultPaths: false
+        })
       } else {
         console.warn('[ACP Init] No runtime paths available to add to PATH')
       }
     }
 
-    // Normalize and set PATH
-    const normalizedPath = this.runtimeHelper.normalizePathEnv(allPaths)
-    env[normalizedPath.key] = normalizedPath.value
-
-    // Add registry environment variables if using builtin runtime
     if (useBuiltinRuntime) {
       if (npmRegistry && npmRegistry !== '') {
         env.npm_config_registry = npmRegistry
@@ -598,8 +567,6 @@ class AcpInitHelper {
         console.log('[ACP Init] Set UV registry:', uvRegistry)
       }
 
-      // On Windows, if app is installed in system directory, set npm prefix to user directory
-      // to avoid permission issues when installing global packages
       if (process.platform === 'win32' && this.runtimeHelper.isInstalledInSystemDirectory()) {
         const userNpmPrefix = this.runtimeHelper.getUserNpmPrefix()
 
@@ -611,47 +578,38 @@ class AcpInitHelper {
             userNpmPrefix
           )
 
-          // Add user npm bin directory to PATH
-          const pathKey = 'Path'
-          const separator = ';'
-          const existingPath = env[pathKey] || ''
           const userNpmBinPath = userNpmPrefix
-
-          // Ensure the user npm bin path is at the beginning of PATH
-          if (existingPath) {
-            env[pathKey] = [userNpmBinPath, existingPath].filter(Boolean).join(separator)
-          } else {
-            env[pathKey] = userNpmBinPath
-          }
+          setPathEntriesOnEnv(env, [userNpmBinPath, getPathEntriesFromEnv(env)], {
+            includeDefaultPaths: false
+          })
 
           console.log('[ACP Init] Added user npm bin directory to PATH:', userNpmBinPath)
         }
       }
     }
 
-    // Add custom environment variables from profile
     if (profile.env) {
       const customEnvCount = Object.entries(profile.env).filter(
         ([, value]) => value !== undefined && value !== ''
       ).length
       Object.entries(profile.env).forEach(([key, value]) => {
-        if (value !== undefined && value !== '') {
-          if (['PATH', 'Path', 'path'].includes(key)) {
-            // Merge PATH variables
-            const pathKey = process.platform === 'win32' ? 'Path' : 'PATH'
-            const separator = process.platform === 'win32' ? ';' : ':'
-            const existingPath = env[pathKey] || env[normalizedPath.key] || ''
-            env[pathKey] = [value, existingPath].filter(Boolean).join(separator)
-            console.log('[ACP Init] Merged custom PATH from profile:', {
-              customPath: value,
-              mergedPathLength: env[pathKey].length
-            })
-          } else {
-            env[key] = value
-            console.log('[ACP Init] Added custom env var:', key)
-          }
+        if (value !== undefined && value !== '' && !['PATH', 'Path', 'path'].includes(key)) {
+          env[key] = value
+          console.log('[ACP Init] Added custom env var:', key)
         }
       })
+
+      const customPathEntries = getPathEntriesFromEnv(profile.env)
+      if (customPathEntries.length > 0) {
+        setPathEntriesOnEnv(env, [customPathEntries, getPathEntriesFromEnv(env)], {
+          includeDefaultPaths: false
+        })
+        console.log('[ACP Init] Merged custom PATH from profile:', {
+          customPath: profile.env.PATH || profile.env.Path || profile.env.path,
+          mergedPathLength: env[process.platform === 'win32' ? 'Path' : 'PATH']?.length || 0
+        })
+      }
+
       console.log('[ACP Init] Added custom environment variables from profile:', customEnvCount)
     }
 
diff --git a/src/main/presenter/configPresenter/index.ts b/src/main/presenter/configPresenter/index.ts
index 6a2125ebf..22767fa29 100644
--- a/src/main/presenter/configPresenter/index.ts
+++ b/src/main/presenter/configPresenter/index.ts
@@ -16,7 +16,8 @@ import {
   AcpAgentState,
   AcpManualAgent,
   AcpRegistryAgent,
-  AcpResolvedLaunchSpec
+  AcpResolvedLaunchSpec,
+  ProviderDbRefreshResult
 } from '@shared/presenter'
 import { ProviderBatchUpdate } from '@shared/provider-operations'
 import { SearchEngineTemplate } from '@shared/chat'
@@ -343,7 +344,9 @@ export class ConfigPresenter implements IConfigPresenter {
     this.initProviderModelsDir()
 
     // 初始化 Provider DB（外部聚合 JSON，本地内置为兜底）
-    providerDbLoader.initialize().catch(() => {})
+    providerDbLoader.initialize().catch((error) => {
+      console.warn('[ConfigPresenter] Failed to initialize provider DB:', error)
+    })
 
     // If application version is updated, update appVersion
     if (this.store.get('appVersion') !== this.currentAppVersion) {
@@ -524,6 +527,10 @@ export class ConfigPresenter implements IConfigPresenter {
     return providerDbLoader.getDb()
   }
 
+  async refreshProviderDb(force = false): Promise<ProviderDbRefreshResult> {
+    return providerDbLoader.refreshIfNeeded(force)
+  }
+
   supportsReasoningCapability(providerId: string, modelId: string): boolean {
     return modelCapabilities.supportsReasoning(providerId, modelId)
   }
diff --git a/src/main/presenter/configPresenter/providerDbLoader.ts b/src/main/presenter/configPresenter/providerDbLoader.ts
index bf4b98b8a..0cc742fcd 100644
--- a/src/main/presenter/configPresenter/providerDbLoader.ts
+++ b/src/main/presenter/configPresenter/providerDbLoader.ts
@@ -22,12 +22,20 @@ type MetaFile = {
   lastAttemptedAt?: number
 }
 
+export type ProviderDbRefreshResult = {
+  status: 'updated' | 'not-modified' | 'skipped' | 'error'
+  lastUpdated: number | null
+  providersCount: number
+  message?: string
+}
+
 export class ProviderDbLoader {
   private cache: ProviderAggregate | null = null
   private userDataDir: string
   private cacheDir: string
   private cacheFilePath: string
   private metaFilePath: string
+  private refreshPromise: Promise<ProviderDbRefreshResult> | null = null
 
   constructor() {
     this.userDataDir = app.getPath('userData')
@@ -53,8 +61,16 @@ export class ProviderDbLoader {
       } catch {}
     }
 
-    // Background refresh if needed (npm 缓存风格)
-    this.refreshIfNeeded().catch(() => {})
+    // Always refresh once in the background on startup to pick up upstream updates.
+    void this.refreshIfNeeded(true)
+      .then((result) => {
+        if (result.status === 'error') {
+          console.warn('[ProviderDbLoader] Startup refresh failed:', result.message)
+        }
+      })
+      .catch((error) => {
+        console.warn('[ProviderDbLoader] Startup refresh failed:', error)
+      })
   }
 
   getDb(): ProviderAggregate | null {
@@ -135,8 +151,8 @@ export class ProviderDbLoader {
 
   private getTtlHours(): number {
     const env = process.env.PROVIDER_DB_TTL_HOURS
-    const v = env ? Number(env) : 12
-    return Number.isFinite(v) && v > 0 ? v : 12
+    const v = env ? Number(env) : 4
+    return Number.isFinite(v) && v > 0 ? v : 4
   }
 
   private getProviderDbUrl(): string {
@@ -149,20 +165,58 @@ export class ProviderDbLoader {
     return DEFAULT_PROVIDER_DB_URL
   }
 
-  async refreshIfNeeded(force = false): Promise<void> {
+  async refreshIfNeeded(force = false): Promise<ProviderDbRefreshResult> {
+    if (this.refreshPromise) return this.refreshPromise
+
     const meta = this.readMeta()
     const ttlHours = this.getTtlHours()
     const url = this.getProviderDbUrl()
 
     const needFirstFetch = !meta || !fs.existsSync(this.cacheFilePath)
-    const expired = meta ? this.now() - meta.lastUpdated > ttlHours * 3600 * 1000 : true
+    const freshnessTimestamp = meta?.lastAttemptedAt ?? meta?.lastUpdated ?? 0
+    const expired = meta ? this.now() - freshnessTimestamp > ttlHours * 3600 * 1000 : true
 
-    if (!force && !needFirstFetch && !expired) return
+    if (!force && !needFirstFetch && !expired) {
+      return this.createResult('skipped', meta)
+    }
 
-    await this.fetchAndUpdate(url, meta || undefined)
+    this.refreshPromise = this.fetchAndUpdate(url, meta || undefined).finally(() => {
+      this.refreshPromise = null
+    })
+
+    return this.refreshPromise
   }
 
-  private async fetchAndUpdate(url: string, prevMeta?: MetaFile): Promise<void> {
+  private createResult(
+    status: ProviderDbRefreshResult['status'],
+    meta?: MetaFile | null,
+    message?: string
+  ): ProviderDbRefreshResult {
+    const db = this.getDb()
+    const providersCount = Object.keys(db?.providers || {}).length
+    return {
+      status,
+      lastUpdated: meta?.lastUpdated ?? null,
+      providersCount,
+      ...(message ? { message } : {})
+    }
+  }
+
+  private createAttemptMeta(
+    prevMeta: MetaFile | undefined,
+    url: string,
+    now: number
+  ): MetaFile | null {
+    if (!prevMeta) return null
+    return {
+      ...prevMeta,
+      sourceUrl: url,
+      ttlHours: this.getTtlHours(),
+      lastAttemptedAt: now
+    }
+  }
+
+  private async fetchAndUpdate(url: string, prevMeta?: MetaFile): Promise<ProviderDbRefreshResult> {
     const controller = new AbortController()
     const timeout = setTimeout(() => controller.abort(), 15000)
     try {
@@ -173,40 +227,44 @@ export class ProviderDbLoader {
       const now = this.now()
 
       if (res.status === 304 && prevMeta) {
-        // Not modified; update attempted time only
-        this.writeMeta({ ...prevMeta, lastAttemptedAt: now })
-        return
+        const meta: MetaFile = {
+          ...prevMeta,
+          sourceUrl: url,
+          ttlHours: this.getTtlHours(),
+          lastAttemptedAt: now
+        }
+        this.writeMeta(meta)
+        return this.createResult('not-modified', meta)
       }
 
       if (!res.ok) {
-        // Keep old cache
-        const meta = prevMeta ? { ...prevMeta, lastAttemptedAt: now } : undefined
+        const meta = this.createAttemptMeta(prevMeta, url, now)
         if (meta) this.writeMeta(meta)
-        return
+        return this.createResult('error', meta, `Request failed with status ${res.status}`)
       }
 
       const text = await res.text()
       // Size guard (≈ 5MB)
       if (text.length > 5 * 1024 * 1024) {
-        const meta = prevMeta ? { ...prevMeta, lastAttemptedAt: now } : undefined
+        const meta = this.createAttemptMeta(prevMeta, url, now)
         if (meta) this.writeMeta(meta)
-        return
+        return this.createResult('error', meta, 'Provider DB payload exceeds size limit')
       }
 
       let parsed: unknown
       try {
         parsed = JSON.parse(text)
       } catch {
-        const meta = prevMeta ? { ...prevMeta, lastAttemptedAt: now } : undefined
+        const meta = this.createAttemptMeta(prevMeta, url, now)
         if (meta) this.writeMeta(meta)
-        return
+        return this.createResult('error', meta, 'Provider DB payload is not valid JSON')
       }
 
       const sanitized = sanitizeAggregate(parsed)
       if (!sanitized) {
-        const meta = prevMeta ? { ...prevMeta, lastAttemptedAt: now } : undefined
+        const meta = this.createAttemptMeta(prevMeta, url, now)
         if (meta) this.writeMeta(meta)
-        return
+        return this.createResult('error', meta, 'Provider DB payload failed validation')
       }
 
       const etag = res.headers.get('etag') || undefined
@@ -229,8 +287,12 @@ export class ProviderDbLoader {
           lastUpdated: meta.lastUpdated
         })
       } catch {}
-    } catch {
-      // ignore
+      return this.createResult('updated', meta)
+    } catch (error) {
+      const meta = this.createAttemptMeta(prevMeta, url, this.now())
+      if (meta) this.writeMeta(meta)
+      const message = error instanceof Error ? error.message : 'Unknown provider DB refresh error'
+      return this.createResult('error', meta, message)
     } finally {
       clearTimeout(timeout)
     }
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts b/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts
index 0b6cba52b..c8a21d52f 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts
@@ -18,7 +18,12 @@ import type {
   AcpResolvedLaunchSpec
 } from '@shared/presenter'
 import type { AgentProcessHandle, AgentProcessManager } from './types'
-import { getShellEnvironment } from '@/lib/agentRuntime/shellEnvHelper'
+import {
+  getPathEntriesFromEnv,
+  getShellEnvironment,
+  mergeCommandEnvironment,
+  setPathEntriesOnEnv
+} from '@/lib/agentRuntime/shellEnvHelper'
 import { RuntimeHelper } from '@/lib/runtimeHelper'
 import { buildClientCapabilities } from './acpCapabilities'
 import { AcpFsHandler } from './acpFsHandler'
@@ -798,36 +803,13 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
     const processedArgs = expandedArgs
 
     const HOME_DIR = app.getPath('home')
-    const env: Record<string, string> = {}
-    Object.entries(process.env).forEach(([key, value]) => {
-      if (value !== undefined && value !== '') {
-        env[key] = value
-      }
-    })
-    let pathKey = process.platform === 'win32' ? 'Path' : 'PATH'
-    let pathValue = ''
-
-    // Collect existing PATH values
-    const existingPaths: string[] = []
-    const pathKeys = ['PATH', 'Path', 'path']
-    pathKeys.forEach((key) => {
-      const value = env[key]
-      if (value) {
-        existingPaths.push(value)
-      }
-    })
+    let env = mergeCommandEnvironment()
 
-    // Get shell environment variables for ALL commands (not just Node.js commands)
-    // This ensures commands like kimi-cli can find their dependencies in Release builds
     let shellEnv: Record<string, string> = {}
     try {
       shellEnv = await getShellEnvironment()
       console.info(`[ACP] Retrieved shell environment variables for agent ${agent.id}`)
-      Object.entries(shellEnv).forEach(([key, value]) => {
-        if (value !== undefined && value !== '' && !pathKeys.includes(key)) {
-          env[key] = value
-        }
-      })
+      env = mergeCommandEnvironment({ shellEnv })
     } catch (error) {
       console.warn(
         `[ACP] Failed to get shell environment variables for agent ${agent.id}, using fallback:`,
@@ -835,37 +817,16 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
       )
     }
 
-    // Get shell PATH if available (priority: shell PATH > existing PATH)
     const shellPath = shellEnv.PATH || shellEnv.Path || shellEnv.path
     if (shellPath) {
-      const shellPaths = shellPath.split(process.platform === 'win32' ? ';' : ':')
-      existingPaths.unshift(...shellPaths)
       console.info(`[ACP] Using shell PATH for agent ${agent.id} (length: ${shellPath.length})`)
     }
 
-    // Get default paths
-    const defaultPaths = this.runtimeHelper.getDefaultPaths(HOME_DIR)
-
-    // Merge all paths (priority: shell PATH > existing PATH > default paths)
-    const allPaths = [...existingPaths, ...defaultPaths]
-
-    // Normalize and set PATH
-    const normalized = this.runtimeHelper.normalizePathEnv(allPaths)
-    pathKey = normalized.key
-    pathValue = normalized.value
-    env[pathKey] = pathValue
-
     // Merge distribution/base environment variables first.
     if (launchSpec.env) {
       Object.entries(launchSpec.env).forEach(([key, value]) => {
         if (value !== undefined && value !== '') {
-          if (['PATH', 'Path', 'path'].includes(key)) {
-            const currentPathKey = process.platform === 'win32' ? 'Path' : 'PATH'
-            const separator = process.platform === 'win32' ? ';' : ':'
-            env[currentPathKey] = env[currentPathKey]
-              ? `${value}${separator}${env[currentPathKey]}`
-              : value
-          } else {
+          if (!['PATH', 'Path', 'path'].includes(key)) {
             env[key] = value
           }
         }
@@ -899,12 +860,28 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
     if (userEnvOverride) {
       Object.entries(userEnvOverride).forEach(([key, value]) => {
         if (value !== undefined && value !== '') {
-          env[key] = value
+          if (!['PATH', 'Path', 'path'].includes(key)) {
+            env[key] = value
+          }
         }
       })
     }
 
+    setPathEntriesOnEnv(
+      env,
+      [
+        getPathEntriesFromEnv(userEnvOverride),
+        getPathEntriesFromEnv(launchSpec.env),
+        getPathEntriesFromEnv(env)
+      ],
+      {
+        includeDefaultPaths: false
+      }
+    )
+
     const mergedEnv = env
+    const pathKey = process.platform === 'win32' ? 'Path' : 'PATH'
+    const pathValue = mergedEnv[pathKey] || mergedEnv.PATH || ''
 
     console.info(`[ACP] Environment variables for agent ${agent.id}:`, {
       pathKey,
diff --git a/src/main/presenter/skillPresenter/skillExecutionService.ts b/src/main/presenter/skillPresenter/skillExecutionService.ts
index 5e1fead96..580f63a78 100644
--- a/src/main/presenter/skillPresenter/skillExecutionService.ts
+++ b/src/main/presenter/skillPresenter/skillExecutionService.ts
@@ -11,7 +11,11 @@ import type {
 } from '@shared/types/skill'
 import { backgroundExecSessionManager } from '@/lib/agentRuntime/backgroundExecSessionManager'
 import { rtkRuntimeService } from '@/lib/agentRuntime/rtkRuntimeService'
-import { getShellEnvironment, getUserShell } from '@/lib/agentRuntime/shellEnvHelper'
+import {
+  getShellEnvironment,
+  getUserShell,
+  mergeCommandEnvironment
+} from '@/lib/agentRuntime/shellEnvHelper'
 import { resolveSessionDir } from '@/lib/agentRuntime/sessionPaths'
 import { RuntimeHelper } from '@/lib/runtimeHelper'
 
@@ -61,12 +65,6 @@ interface SpawnPlan {
   spawnMode: 'direct' | 'shell'
 }
 
-function toStringEnv(input: NodeJS.ProcessEnv | Record<string, string>): Record<string, string> {
-  return Object.fromEntries(
-    Object.entries(input).filter((entry): entry is [string, string] => typeof entry[1] === 'string')
-  )
-}
-
 export class SkillExecutionService {
   private readonly runtimeHelper = RuntimeHelper.getInstance()
   private readonly configPresenter?: Pick<IConfigPresenter, 'getSetting'>
@@ -144,13 +142,14 @@ export class SkillExecutionService {
     const extension = await this.skillPresenter.getSkillExtension(input.skill)
     const shellEnv = await getShellEnvironment()
     const executionCwd = await this.resolveExecutionCwd(conversationId, metadata.skillRoot)
-    const mergedEnv = {
-      ...toStringEnv(process.env),
-      ...shellEnv,
-      ...extension.env,
-      SKILL_ROOT: metadata.skillRoot,
-      DEEPCHAT_SKILL_ROOT: metadata.skillRoot
-    }
+    const mergedEnv = mergeCommandEnvironment({
+      shellEnv,
+      overrides: {
+        ...extension.env,
+        SKILL_ROOT: metadata.skillRoot,
+        DEEPCHAT_SKILL_ROOT: metadata.skillRoot
+      }
+    })
 
     const runtime = await this.resolveRuntimeCommand(
       script,
diff --git a/src/main/presenter/toolPresenter/agentTools/agentBashHandler.ts b/src/main/presenter/toolPresenter/agentTools/agentBashHandler.ts
index 002e98b46..05dbebf86 100644
--- a/src/main/presenter/toolPresenter/agentTools/agentBashHandler.ts
+++ b/src/main/presenter/toolPresenter/agentTools/agentBashHandler.ts
@@ -9,7 +9,11 @@ import { getBackgroundExecConfig } from '@/lib/agentRuntime/backgroundExecSessio
 import { backgroundExecSessionManager } from '@/lib/agentRuntime/backgroundExecSessionManager'
 import { terminateProcessTree } from '@/lib/agentRuntime/processTree'
 import { rtkRuntimeService } from '@/lib/agentRuntime/rtkRuntimeService'
-import { getShellEnvironment, getUserShell } from '@/lib/agentRuntime/shellEnvHelper'
+import {
+  getShellEnvironment,
+  getUserShell,
+  mergeCommandEnvironment
+} from '@/lib/agentRuntime/shellEnvHelper'
 import { resolveSessionDir } from '@/lib/agentRuntime/sessionPaths'
 
 // Consider moving to a shared handlers location in future refactoring
@@ -323,17 +327,12 @@ export class AgentBashHandler {
     options: ExecuteCommandOptions
   ): Promise<CompletedShellProcessResult> {
     const { shell, args } = getUserShell()
-    const shellEnv = await getShellEnvironment()
     const outputFilePath = this.createOutputFilePath(options.conversationId, options.outputPrefix)
 
     return new Promise((resolve, reject) => {
       const child = spawn(shell, [...args, command], {
         cwd,
-        env: {
-          ...process.env,
-          ...shellEnv,
-          ...options.env
-        },
+        env: options.env ? { ...options.env } : { ...process.env },
         detached: process.platform !== 'win32',
         stdio: ['pipe', 'pipe', 'pipe']
       })
@@ -591,10 +590,14 @@ export class AgentBashHandler {
   ): Promise<PreparedCommand> {
     const baseEnv = env ?? {}
     if (!this.configPresenter) {
+      const shellEnv = await getShellEnvironment()
       return {
         originalCommand: command,
         command,
-        env: baseEnv,
+        env: mergeCommandEnvironment({
+          shellEnv,
+          overrides: baseEnv
+        }),
         rewritten: false,
         rtkApplied: false,
         rtkMode: 'bypass',
diff --git a/src/renderer/settings/components/DataSettings.vue b/src/renderer/settings/components/DataSettings.vue
index 61842c1db..90505fd92 100644
--- a/src/renderer/settings/components/DataSettings.vue
+++ b/src/renderer/settings/components/DataSettings.vue
@@ -147,6 +147,40 @@
       <!-- 分割线 -->
       <Separator class="my-4" />
 
+      <div class="flex flex-col gap-3 p-4 border border-border rounded-lg bg-card/30">
+        <div class="flex flex-row gap-3 items-start" :dir="languageStore.dir">
+          <Icon icon="lucide:refresh-cw" class="w-4 h-4 text-muted-foreground mt-1" />
+          <div class="flex flex-col gap-1">
+            <div class="text-sm font-medium">{{ t('settings.data.modelConfigUpdate.title') }}</div>
+            <p class="text-xs text-muted-foreground">
+              {{ t('settings.data.modelConfigUpdate.description') }}
+            </p>
+          </div>
+        </div>
+        <Button
+          variant="outline"
+          class="w-40"
+          :disabled="isUpdatingModelConfig"
+          :dir="languageStore.dir"
+          @click="handleRefreshProviderDb"
+        >
+          <Icon
+            :icon="isUpdatingModelConfig ? 'lucide:loader-2' : 'lucide:refresh-cw'"
+            class="w-4 h-4 text-muted-foreground"
+            :class="isUpdatingModelConfig ? 'animate-spin' : ''"
+          />
+          <span class="text-sm font-medium">
+            {{
+              isUpdatingModelConfig
+                ? t('settings.data.modelConfigUpdate.updating')
+                : t('settings.data.modelConfigUpdate.button')
+            }}
+          </span>
+        </Button>
+      </div>
+
+      <Separator class="my-4" />
+
       <!-- 数据重置选项 -->
       <AlertDialog v-model:open="isResetDialogOpen">
         <AlertDialogTrigger as-child>
@@ -372,6 +406,7 @@ const languageStore = useLanguageStore()
 const syncStore = useSyncStore()
 const devicePresenter = usePresenter('devicePresenter')
 const yoBrowserPresenter = usePresenter('yoBrowserPresenter')
+const configPresenter = usePresenter('configPresenter')
 const { backups: backupsRef } = storeToRefs(syncStore)
 const { toast } = useToast()
 
@@ -382,6 +417,7 @@ const selectedBackup = ref('')
 const isResetDialogOpen = ref(false)
 const resetType = ref<'chat' | 'knowledge' | 'config' | 'all'>('chat')
 const isResetting = ref(false)
+const isUpdatingModelConfig = ref(false)
 const isClearingSandbox = ref(false)
 const isClearSandboxDialogOpen = ref(false)
 
@@ -462,6 +498,51 @@ const handleBackup = async () => {
   })
 }
 
+const handleRefreshProviderDb = async () => {
+  if (isUpdatingModelConfig.value) return
+
+  isUpdatingModelConfig.value = true
+  try {
+    const result = await configPresenter.refreshProviderDb(true)
+
+    if (!result || result.status === 'error') {
+      console.error('Failed to refresh provider DB:', result?.message)
+      toast({
+        title: t('settings.data.modelConfigUpdate.failedTitle'),
+        description: t('settings.data.modelConfigUpdate.failedDescription'),
+        variant: 'destructive',
+        duration: 4000
+      })
+      return
+    }
+
+    const isUpToDate = result.status === 'not-modified' || result.status === 'skipped'
+    toast({
+      title: t(
+        isUpToDate
+          ? 'settings.data.modelConfigUpdate.upToDateTitle'
+          : 'settings.data.modelConfigUpdate.updatedTitle'
+      ),
+      description: t(
+        isUpToDate
+          ? 'settings.data.modelConfigUpdate.upToDateDescription'
+          : 'settings.data.modelConfigUpdate.updatedDescription'
+      ),
+      duration: 4000
+    })
+  } catch (error) {
+    console.error('Failed to refresh provider DB:', error)
+    toast({
+      title: t('settings.data.modelConfigUpdate.failedTitle'),
+      description: t('settings.data.modelConfigUpdate.failedDescription'),
+      variant: 'destructive',
+      duration: 4000
+    })
+  } finally {
+    isUpdatingModelConfig.value = false
+  }
+}
+
 // 关闭导入对话框
 const closeImportDialog = () => {
   isImportDialogOpen.value = false
diff --git a/src/renderer/src/components/chat/mentions/SuggestionList.vue b/src/renderer/src/components/chat/mentions/SuggestionList.vue
index 9fd9946e0..7ca37d562 100644
--- a/src/renderer/src/components/chat/mentions/SuggestionList.vue
+++ b/src/renderer/src/components/chat/mentions/SuggestionList.vue
@@ -10,7 +10,17 @@
         @click="selectIndex(index)"
       >
         <div class="flex items-start gap-2">
-          <span class="mt-0.5 text-xs text-muted-foreground">{{ categoryTag(item.category) }}</span>
+          <span
+            class="mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center text-xs text-muted-foreground"
+          >
+            <Icon
+              v-if="item.category === 'command'"
+              icon="lucide:command"
+              data-icon="lucide:command"
+              class="h-3.5 w-3.5"
+            />
+            <span v-else>{{ categoryTag(item.category) }}</span>
+          </span>
           <div class="flex-1 min-w-0">
             <div class="truncate font-medium">{{ item.label }}</div>
             <div v-if="item.description" class="truncate text-xs text-muted-foreground">
@@ -26,6 +36,7 @@
 
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
+import { Icon } from '@iconify/vue'
 
 export type SuggestionCategory = 'file' | 'command' | 'skill' | 'prompt' | 'tool'
 
diff --git a/src/renderer/src/i18n/da-DK/settings.json b/src/renderer/src/i18n/da-DK/settings.json
index 27d2c0b64..d752b71e1 100644
--- a/src/renderer/src/i18n/da-DK/settings.json
+++ b/src/renderer/src/i18n/da-DK/settings.json
@@ -117,6 +117,18 @@
       "backupSuccessTitle": "Backup lykkedes",
       "backupSuccessMessage": "Data blev sikkerhedskopieret"
     },
+    "modelConfigUpdate": {
+      "title": "Opdater modelkonfiguration",
+      "description": "Tving en opdatering af provider.json fra upstream for at hente de nyeste modelkapaciteter og standardindstillinger.",
+      "button": "Opdater nu",
+      "updating": "Opdaterer...",
+      "updatedTitle": "Modelkonfiguration opdateret",
+      "updatedDescription": "De seneste providerdata er blevet hentet.",
+      "upToDateTitle": "Allerede opdateret",
+      "upToDateDescription": "Den lokale modelkonfiguration bruger allerede de nyeste providerdata.",
+      "failedTitle": "Opdatering mislykkedes",
+      "failedDescription": "Modelkonfigurationen kunne ikke opdateres lige nu. Prøv igen senere."
+    },
     "yoBrowser": {
       "clearButton": "Ryd YoBrowser-data",
       "clearFailedDescription": "Prøv venligst igen, eller tjek logfilerne for at få flere oplysninger.",
diff --git a/src/renderer/src/i18n/en-US/settings.json b/src/renderer/src/i18n/en-US/settings.json
index fc0f76266..64032f121 100644
--- a/src/renderer/src/i18n/en-US/settings.json
+++ b/src/renderer/src/i18n/en-US/settings.json
@@ -233,6 +233,18 @@
       "backupSuccessTitle": "Backup successful",
       "backupSuccessMessage": "Data backed up successfully"
     },
+    "modelConfigUpdate": {
+      "title": "Update Model Config",
+      "description": "Force refresh provider.json from upstream to update model capabilities and default model settings.",
+      "button": "Update Now",
+      "updating": "Updating...",
+      "updatedTitle": "Model config updated",
+      "updatedDescription": "The latest provider metadata has been refreshed.",
+      "upToDateTitle": "Already up to date",
+      "upToDateDescription": "Your local model config is already using the latest provider metadata.",
+      "failedTitle": "Update failed",
+      "failedDescription": "Unable to refresh model config right now. Please try again later."
+    },
     "yoBrowser": {
       "clearButton": "Clear YoBrowser data",
       "clearFailedDescription": "Please try again or check the logs for more information.",
diff --git a/src/renderer/src/i18n/fa-IR/settings.json b/src/renderer/src/i18n/fa-IR/settings.json
index eafd4cde8..9665f52f0 100644
--- a/src/renderer/src/i18n/fa-IR/settings.json
+++ b/src/renderer/src/i18n/fa-IR/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "پشتیبان گیری با موفقیت انجام شد",
       "backupSuccessMessage": "داده ها با موفقیت پشتیبان گیری شدند"
     },
+    "modelConfigUpdate": {
+      "title": "به‌روزرسانی پیکربندی مدل",
+      "description": "برای به‌روزرسانی قابلیت‌های مدل و تنظیمات پیش‌فرض، فایل provider.json را از مبدأ به‌صورت اجباری تازه‌سازی می‌کند.",
+      "button": "اکنون به‌روزرسانی کن",
+      "updating": "در حال به‌روزرسانی...",
+      "updatedTitle": "پیکربندی مدل به‌روز شد",
+      "updatedDescription": "آخرین فرادادهٔ ارائه‌دهنده دریافت شد.",
+      "upToDateTitle": "از قبل به‌روز است",
+      "upToDateDescription": "پیکربندی محلی مدل همین حالا هم از تازه‌ترین فرادادهٔ ارائه‌دهنده استفاده می‌کند.",
+      "failedTitle": "به‌روزرسانی ناموفق بود",
+      "failedDescription": "فعلاً امکان به‌روزرسانی پیکربندی مدل وجود ندارد. کمی بعد دوباره تلاش کنید."
+    },
     "yoBrowser": {
       "clearButton": "داده های YoBrowser را پاک کنید",
       "clearFailedDescription": "لطفاً دوباره امتحان کنید یا برای اطلاعات بیشتر گزارش‌ها را بررسی کنید.",
diff --git a/src/renderer/src/i18n/fr-FR/settings.json b/src/renderer/src/i18n/fr-FR/settings.json
index 27c6b923f..d93dcdc4d 100644
--- a/src/renderer/src/i18n/fr-FR/settings.json
+++ b/src/renderer/src/i18n/fr-FR/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "Sauvegarde réussie",
       "backupSuccessMessage": "Données sauvegardées avec succès"
     },
+    "modelConfigUpdate": {
+      "title": "Mettre à jour la config des modèles",
+      "description": "Force la mise à jour de provider.json depuis la source afin d’actualiser les capacités des modèles et les réglages par défaut.",
+      "button": "Mettre à jour",
+      "updating": "Mise à jour...",
+      "updatedTitle": "Configuration des modèles mise à jour",
+      "updatedDescription": "Les dernières métadonnées des fournisseurs ont bien été récupérées.",
+      "upToDateTitle": "Déjà à jour",
+      "upToDateDescription": "La configuration locale utilise déjà les métadonnées fournisseur les plus récentes.",
+      "failedTitle": "Mise à jour impossible",
+      "failedDescription": "Impossible d’actualiser la configuration des modèles pour le moment. Réessayez plus tard."
+    },
     "yoBrowser": {
       "clearButton": "Effacer les données de YoBrowser",
       "clearFailedDescription": "Veuillez réessayer ou consulter les journaux pour plus d'informations.",
diff --git a/src/renderer/src/i18n/he-IL/settings.json b/src/renderer/src/i18n/he-IL/settings.json
index 3162dbc39..ed6049296 100644
--- a/src/renderer/src/i18n/he-IL/settings.json
+++ b/src/renderer/src/i18n/he-IL/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "גיבוי הושלם בהצלחה",
       "backupSuccessMessage": "הנתונים גובו בהצלחה"
     },
+    "modelConfigUpdate": {
+      "title": "עדכון הגדרות המודלים",
+      "description": "מרענן בכפייה את provider.json מהמקור כדי לעדכן יכולות מודל והגדרות ברירת מחדל.",
+      "button": "עדכן עכשיו",
+      "updating": "מעדכן...",
+      "updatedTitle": "הגדרות המודלים עודכנו",
+      "updatedDescription": "מטא־הנתונים העדכניים של הספקים נטענו בהצלחה.",
+      "upToDateTitle": "כבר מעודכן",
+      "upToDateDescription": "הגדרות המודלים המקומיות כבר משתמשות במטא־הנתונים העדכניים ביותר של הספקים.",
+      "failedTitle": "העדכון נכשל",
+      "failedDescription": "כרגע אי אפשר לעדכן את הגדרות המודלים. נסה שוב מאוחר יותר."
+    },
     "yoBrowser": {
       "clearButton": "נקה את נתוני YoBrowser",
       "clearFailedDescription": "אנא נסה שוב או בדוק את היומנים לקבלת מידע נוסף.",
diff --git a/src/renderer/src/i18n/ja-JP/settings.json b/src/renderer/src/i18n/ja-JP/settings.json
index 9133bb0a8..082ad073e 100644
--- a/src/renderer/src/i18n/ja-JP/settings.json
+++ b/src/renderer/src/i18n/ja-JP/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "バックアップ成功",
       "backupSuccessMessage": "データは正常にバックアップされました"
     },
+    "modelConfigUpdate": {
+      "title": "モデル設定を更新",
+      "description": "上流の provider.json を強制的に更新し、モデル機能と既定設定を最新の状態にします。",
+      "button": "今すぐ更新",
+      "updating": "更新中...",
+      "updatedTitle": "モデル設定を更新しました",
+      "updatedDescription": "プロバイダーの最新メタデータを取得しました。",
+      "upToDateTitle": "すでに最新です",
+      "upToDateDescription": "ローカルのモデル設定は、すでに最新のプロバイダーメタデータを使用しています。",
+      "failedTitle": "更新に失敗しました",
+      "failedDescription": "現在モデル設定を更新できません。しばらくしてからもう一度お試しください。"
+    },
     "yoBrowser": {
       "clearButton": "YoBrowser データをクリアする",
       "clearFailedDescription": "もう一度試すか、ログで詳細を確認してください。",
diff --git a/src/renderer/src/i18n/ko-KR/settings.json b/src/renderer/src/i18n/ko-KR/settings.json
index ee863133e..7bc573a68 100644
--- a/src/renderer/src/i18n/ko-KR/settings.json
+++ b/src/renderer/src/i18n/ko-KR/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "백업 성공",
       "backupSuccessMessage": "데이터가 성공적으로 백업되었습니다."
     },
+    "modelConfigUpdate": {
+      "title": "모델 설정 업데이트",
+      "description": "업스트림 provider.json을 강제로 새로고침해 모델 기능과 기본 설정을 최신 상태로 맞춥니다.",
+      "button": "지금 업데이트",
+      "updating": "업데이트 중...",
+      "updatedTitle": "모델 설정을 업데이트했습니다",
+      "updatedDescription": "최신 제공자 메타데이터를 가져왔습니다.",
+      "upToDateTitle": "이미 최신 상태입니다",
+      "upToDateDescription": "로컬 모델 설정이 이미 최신 제공자 메타데이터를 사용하고 있습니다.",
+      "failedTitle": "업데이트에 실패했습니다",
+      "failedDescription": "지금은 모델 설정을 업데이트할 수 없습니다. 잠시 후 다시 시도하세요."
+    },
     "yoBrowser": {
       "clearButton": "YoBrowser 데이터 지우기",
       "clearFailedDescription": "자세한 내용은 다시 시도하거나 로그를 확인하세요.",
diff --git a/src/renderer/src/i18n/pt-BR/settings.json b/src/renderer/src/i18n/pt-BR/settings.json
index 2c30b4cc2..d2de985cb 100644
--- a/src/renderer/src/i18n/pt-BR/settings.json
+++ b/src/renderer/src/i18n/pt-BR/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "Backup bem-sucedido",
       "backupSuccessMessage": "Dados salvos em backup com sucesso"
     },
+    "modelConfigUpdate": {
+      "title": "Atualizar configuração dos modelos",
+      "description": "Força a atualização do provider.json para trazer as capacidades mais recentes dos modelos e as configurações padrão.",
+      "button": "Atualizar agora",
+      "updating": "Atualizando...",
+      "updatedTitle": "Configuração dos modelos atualizada",
+      "updatedDescription": "Os metadados mais recentes dos provedores foram atualizados.",
+      "upToDateTitle": "Já está atualizado",
+      "upToDateDescription": "A configuração local dos modelos já está usando os metadados mais recentes dos provedores.",
+      "failedTitle": "Falha ao atualizar",
+      "failedDescription": "Não foi possível atualizar a configuração dos modelos agora. Tente novamente mais tarde."
+    },
     "yoBrowser": {
       "clearButton": "Limpar dados do YoBrowser",
       "clearFailedDescription": "Tente novamente ou verifique os registros para obter mais informações.",
diff --git a/src/renderer/src/i18n/ru-RU/settings.json b/src/renderer/src/i18n/ru-RU/settings.json
index b1692366f..bfbba473d 100644
--- a/src/renderer/src/i18n/ru-RU/settings.json
+++ b/src/renderer/src/i18n/ru-RU/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "Резервное копирование выполнено успешно",
       "backupSuccessMessage": "Резервное копирование данных успешно выполнено"
     },
+    "modelConfigUpdate": {
+      "title": "Обновить конфигурацию моделей",
+      "description": "Принудительно обновляет provider.json из источника, чтобы подтянуть актуальные возможности моделей и настройки по умолчанию.",
+      "button": "Обновить сейчас",
+      "updating": "Обновление...",
+      "updatedTitle": "Конфигурация моделей обновлена",
+      "updatedDescription": "Получены актуальные метаданные провайдеров.",
+      "upToDateTitle": "Уже актуально",
+      "upToDateDescription": "Локальная конфигурация моделей уже использует актуальные метаданные провайдеров.",
+      "failedTitle": "Не удалось обновить",
+      "failedDescription": "Сейчас не удалось обновить конфигурацию моделей. Попробуйте позже."
+    },
     "yoBrowser": {
       "clearButton": "Очистить данные YoBrowser",
       "clearFailedDescription": "Повторите попытку или проверьте журналы для получения дополнительной информации.",
diff --git a/src/renderer/src/i18n/zh-CN/settings.json b/src/renderer/src/i18n/zh-CN/settings.json
index d6fb802bc..e0c7e12aa 100644
--- a/src/renderer/src/i18n/zh-CN/settings.json
+++ b/src/renderer/src/i18n/zh-CN/settings.json
@@ -233,6 +233,18 @@
       "backupSuccessTitle": "备份成功",
       "backupSuccessMessage": "成功备份了数据"
     },
+    "modelConfigUpdate": {
+      "title": "更新模型配置",
+      "description": "从上游强制刷新 provider.json，用最新的服务商元数据更新模型能力与默认配置。",
+      "button": "立即更新",
+      "updating": "更新中...",
+      "updatedTitle": "模型配置已更新",
+      "updatedDescription": "已刷新到最新的服务商元数据。",
+      "upToDateTitle": "已是最新",
+      "upToDateDescription": "当前本地模型配置已使用最新的服务商元数据。",
+      "failedTitle": "更新失败",
+      "failedDescription": "暂时无法刷新模型配置，请稍后重试。"
+    },
     "yoBrowser": {
       "title": "YoBrowser 沙盒",
       "description": "独立的浏览器沙盒，不与主应用共享 Cookie 和本地存储。可在此一键清空 YoBrowser 数据。",
diff --git a/src/renderer/src/i18n/zh-HK/settings.json b/src/renderer/src/i18n/zh-HK/settings.json
index 179ba715d..169bf6afa 100644
--- a/src/renderer/src/i18n/zh-HK/settings.json
+++ b/src/renderer/src/i18n/zh-HK/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "備份成功",
       "backupSuccessMessage": "成功備份了數據"
     },
+    "modelConfigUpdate": {
+      "title": "更新模型設定",
+      "description": "從上游強制重新整理 provider.json，以最新的服務商中繼資料更新模型能力與預設設定。",
+      "button": "立即更新",
+      "updating": "更新中...",
+      "updatedTitle": "模型設定已更新",
+      "updatedDescription": "已重新整理到最新的服務商中繼資料。",
+      "upToDateTitle": "已是最新",
+      "upToDateDescription": "目前本機模型設定已使用最新的服務商中繼資料。",
+      "failedTitle": "更新失敗",
+      "failedDescription": "暫時未能重新整理模型設定，請稍後再試。"
+    },
     "yoBrowser": {
       "clearButton": "清空 YoBrowser 數據",
       "clearFailedDescription": "請重試或查看日誌獲取更多信息。",
diff --git a/src/renderer/src/i18n/zh-TW/settings.json b/src/renderer/src/i18n/zh-TW/settings.json
index 71059bd1d..c003e33d6 100644
--- a/src/renderer/src/i18n/zh-TW/settings.json
+++ b/src/renderer/src/i18n/zh-TW/settings.json
@@ -171,6 +171,18 @@
       "backupSuccessTitle": "備份成功",
       "backupSuccessMessage": "成功備份了數據"
     },
+    "modelConfigUpdate": {
+      "title": "更新模型設定",
+      "description": "從上游強制重新整理 provider.json，以最新的服務商中繼資料更新模型能力與預設設定。",
+      "button": "立即更新",
+      "updating": "更新中...",
+      "updatedTitle": "模型設定已更新",
+      "updatedDescription": "已重新整理為最新的服務商中繼資料。",
+      "upToDateTitle": "已是最新",
+      "upToDateDescription": "目前本機模型設定已使用最新的服務商中繼資料。",
+      "failedTitle": "更新失敗",
+      "failedDescription": "目前無法重新整理模型設定，請稍後再試。"
+    },
     "yoBrowser": {
       "clearButton": "清空 YoBrowser 數據",
       "clearFailedDescription": "請重試或查看日誌獲取更多信息。",
diff --git a/src/shared/types/presenters/legacy.presenters.d.ts b/src/shared/types/presenters/legacy.presenters.d.ts
index d0c4cec32..7031cfad3 100644
--- a/src/shared/types/presenters/legacy.presenters.d.ts
+++ b/src/shared/types/presenters/legacy.presenters.d.ts
@@ -499,6 +499,13 @@ export interface INotificationPresenter {
 
 import type { ReasoningPortrait } from '../model-db'
 
+export type ProviderDbRefreshResult = {
+  status: 'updated' | 'not-modified' | 'skipped' | 'error'
+  lastUpdated: number | null
+  providersCount: number
+  message?: string
+}
+
 export interface IConfigPresenter {
   getSetting<T>(key: string): T | undefined
   setSetting<T>(key: string, value: T): void
@@ -733,6 +740,7 @@ export interface IConfigPresenter {
   setAutoDetectNpmRegistry?(enabled: boolean): void
   clearNpmRegistryCache?(): void
   getProviderDb(): { providers: Record<string, unknown> } | null
+  refreshProviderDb(force?: boolean): Promise<ProviderDbRefreshResult>
 
   // Default model settings
   getDefaultModel(): { providerId: string; modelId: string } | undefined
diff --git a/test/main/lib/agentRuntime/backgroundExecSessionManager.test.ts b/test/main/lib/agentRuntime/backgroundExecSessionManager.test.ts
index cefee77a8..1419576e8 100644
--- a/test/main/lib/agentRuntime/backgroundExecSessionManager.test.ts
+++ b/test/main/lib/agentRuntime/backgroundExecSessionManager.test.ts
@@ -1,7 +1,13 @@
+import { EventEmitter } from 'events'
 import type { ChildProcess } from 'child_process'
+import { spawn } from 'child_process'
 import fs from 'fs'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+vi.mock('child_process', () => ({
+  spawn: vi.fn()
+}))
+
 vi.mock('electron', () => ({
   app: {
     getPath: vi.fn((name: string) => (name === 'userData' ? '/mock/userData' : '/mock/home'))
@@ -24,6 +30,19 @@ vi.mock('@shared/logger', () => ({
 
 import { BackgroundExecSessionManager } from '@/lib/agentRuntime/backgroundExecSessionManager'
 
+class MockStream extends EventEmitter {}
+
+class MockChildProcess extends EventEmitter {
+  stdout = new MockStream()
+  stderr = new MockStream()
+  stdin = {
+    write: vi.fn(),
+    end: vi.fn(),
+    destroyed: false
+  }
+  pid = 321
+}
+
 describe('BackgroundExecSessionManager', () => {
   let manager: BackgroundExecSessionManager
 
@@ -214,4 +233,39 @@ describe('BackgroundExecSessionManager', () => {
     expect(poll.output).toBe('timeout tail')
     expect(log.output).toBe('timeout tail')
   })
+
+  it('merges the prepared env on top of process env when starting a session', async () => {
+    const child = new MockChildProcess()
+    vi.mocked(spawn).mockReturnValue(child as never)
+    process.env.BASELINE_FLAG = 'baseline'
+
+    try {
+      const result = await manager.start('conv-1', 'echo test', '/workspace', {
+        timeout: 0,
+        env: {
+          PATH: '/prepared/bin:/usr/local/bin',
+          CUSTOM_FLAG: '1'
+        }
+      })
+
+      expect(result).toEqual({
+        sessionId: expect.stringMatching(/^bg_/),
+        status: 'running'
+      })
+      expect(spawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Array),
+        expect.objectContaining({
+          cwd: '/workspace',
+          env: expect.objectContaining({
+            BASELINE_FLAG: 'baseline',
+            PATH: '/prepared/bin:/usr/local/bin',
+            CUSTOM_FLAG: '1'
+          })
+        })
+      )
+    } finally {
+      delete process.env.BASELINE_FLAG
+    }
+  })
 })
diff --git a/test/main/lib/agentRuntime/rtkRuntimeService.test.ts b/test/main/lib/agentRuntime/rtkRuntimeService.test.ts
index 473bd45f7..5c04a4ae1 100644
--- a/test/main/lib/agentRuntime/rtkRuntimeService.test.ts
+++ b/test/main/lib/agentRuntime/rtkRuntimeService.test.ts
@@ -36,7 +36,10 @@ function createService(runCommand = vi.fn()) {
     },
     getShellEnvironment: vi.fn().mockResolvedValue({ PATH: '/shell/bin' }),
     runCommand,
-    getPath: (name) => (name === 'userData' ? '/mock/userData' : '/mock/temp')
+    getPath: (name) =>
+      name === 'userData'
+        ? path.join(os.tmpdir(), 'deepchat-rtk-userData')
+        : path.join(os.tmpdir(), 'deepchat-rtk-temp')
   })
 
   ;(service as never).healthState = {
@@ -160,7 +163,9 @@ describe('RtkRuntimeService', () => {
       '/runtime/rtk',
       ['rewrite', 'find . -name "*.ts"'],
       expect.objectContaining({
-        env: expect.objectContaining({ PATH: '/shell/bin' })
+        env: expect.objectContaining({
+          PATH: expect.stringContaining('/shell/bin')
+        })
       })
     )
     expect(result.originalCommand).toBe('find . -name "*.ts"')
diff --git a/test/main/lib/agentRuntime/shellEnvHelper.test.ts b/test/main/lib/agentRuntime/shellEnvHelper.test.ts
new file mode 100644
index 000000000..6c34e89e5
--- /dev/null
+++ b/test/main/lib/agentRuntime/shellEnvHelper.test.ts
@@ -0,0 +1,166 @@
+import { EventEmitter } from 'events'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('child_process', () => ({
+  spawn: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  app: {
+    getPath: vi.fn((name: string) => {
+      if (name === 'home') {
+        return process.platform === 'win32' ? 'C:\\Users\\tester' : '/Users/tester'
+      }
+      return '/tmp'
+    })
+  }
+}))
+
+import { spawn } from 'child_process'
+import { clearShellEnvironmentCache, getShellEnvironment } from '@/lib/agentRuntime/shellEnvHelper'
+
+class MockStream extends EventEmitter {}
+
+class MockChild extends EventEmitter {
+  stdout = new MockStream()
+  stderr = new MockStream()
+  kill = vi.fn(() => true)
+}
+
+function getMarkers(command: string) {
+  const matches = [...command.matchAll(/printf '%s\\n' '([^']+)'/g)].map((match) => match[1])
+  return {
+    start: matches[0] ?? '',
+    end: matches[1] ?? ''
+  }
+}
+
+describe('shellEnvHelper', () => {
+  const originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform')
+  const originalEnv = { ...process.env }
+
+  beforeEach(() => {
+    clearShellEnvironmentCache()
+    process.env = { ...originalEnv }
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    clearShellEnvironmentCache()
+    process.env = { ...originalEnv }
+    if (originalPlatform) {
+      Object.defineProperty(process, 'platform', originalPlatform)
+    }
+  })
+
+  it('uses a login interactive zsh shell and preserves /usr/local/bin on macOS', async () => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'darwin'
+    })
+    process.env.SHELL = '/bin/zsh'
+    process.env.PATH = '/usr/bin:/bin'
+
+    vi.mocked(spawn).mockImplementation((shell, args) => {
+      const child = new MockChild()
+      const command = String(args?.[3] ?? '')
+      const { start, end } = getMarkers(command)
+
+      queueMicrotask(() => {
+        child.stdout.emit(
+          'data',
+          [
+            'theme loaded',
+            start,
+            'PATH=/Users/tester/.local/bin:/usr/local/bin',
+            'NVM_DIR=/Users/tester/.nvm',
+            end
+          ].join('\n')
+        )
+        child.emit('exit', 0, null)
+      })
+
+      return child as never
+    })
+
+    const env = await getShellEnvironment()
+
+    expect(spawn).toHaveBeenCalledWith(
+      '/bin/zsh',
+      expect.arrayContaining(['-l', '-i', '-c', expect.any(String)]),
+      expect.any(Object)
+    )
+    expect(env.NVM_DIR).toBe('/Users/tester/.nvm')
+    expect(env.PATH.split(':')).toEqual(
+      expect.arrayContaining(['/Users/tester/.local/bin', '/usr/local/bin', '/usr/bin', '/bin'])
+    )
+  })
+
+  it('falls back to process env on failure and retries instead of caching the failure', async () => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'darwin'
+    })
+    process.env.SHELL = '/bin/zsh'
+    process.env.PATH = '/usr/bin:/bin'
+
+    vi.mocked(spawn)
+      .mockImplementationOnce(() => {
+        const child = new MockChild()
+        queueMicrotask(() => {
+          child.emit('error', new Error('boom'))
+        })
+        return child as never
+      })
+      .mockImplementationOnce((_shell, args) => {
+        const child = new MockChild()
+        const command = String(args?.[3] ?? '')
+        const { start, end } = getMarkers(command)
+
+        queueMicrotask(() => {
+          child.stdout.emit(
+            'data',
+            [start, 'PATH=/custom/bin:/usr/local/bin', 'VOLTA_HOME=/Users/tester/.volta', end].join(
+              '\n'
+            )
+          )
+          child.emit('exit', 0, null)
+        })
+
+        return child as never
+      })
+
+    const fallbackEnv = await getShellEnvironment()
+    expect(fallbackEnv.PATH.split(':')).toEqual(expect.arrayContaining(['/usr/bin', '/bin']))
+
+    const recoveredEnv = await getShellEnvironment()
+    expect(spawn).toHaveBeenCalledTimes(2)
+    expect(recoveredEnv.VOLTA_HOME).toBe('/Users/tester/.volta')
+    expect(recoveredEnv.PATH.split(':')).toEqual(
+      expect.arrayContaining(['/custom/bin', '/usr/local/bin', '/usr/bin', '/bin'])
+    )
+  })
+
+  it('normalizes Path and PATH on Windows without invoking a shell bootstrap process', async () => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'win32'
+    })
+    delete process.env.SHELL
+    process.env.Path = 'C:\\Tools;C:\\Windows\\System32'
+    process.env.PATH = 'C:\\Tools;C:\\Other'
+
+    const env = await getShellEnvironment()
+
+    expect(spawn).not.toHaveBeenCalled()
+    expect(env.Path).toBe(env.PATH)
+    expect(env.Path?.split(';')).toEqual(
+      expect.arrayContaining([
+        'C:\\Tools',
+        'C:\\Windows\\System32',
+        'C:\\Other',
+        'C:\\Users\\tester\\.cargo\\bin'
+      ])
+    )
+  })
+})
diff --git a/test/main/presenter/configPresenter/providerDbLoader.test.ts b/test/main/presenter/configPresenter/providerDbLoader.test.ts
new file mode 100644
index 000000000..cc9eb48b0
--- /dev/null
+++ b/test/main/presenter/configPresenter/providerDbLoader.test.ts
@@ -0,0 +1,260 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+  getPath: vi.fn(),
+  getAppPath: vi.fn(),
+  send: vi.fn()
+}))
+
+vi.mock('fs', async () => {
+  const actual = await vi.importActual<typeof import('node:fs')>('node:fs')
+  return {
+    __esModule: true,
+    ...actual,
+    default: actual
+  }
+})
+
+vi.mock('electron', () => ({
+  app: {
+    getPath: state.getPath,
+    getAppPath: state.getAppPath
+  }
+}))
+
+vi.mock('@/eventbus', () => ({
+  eventBus: {
+    send: state.send
+  },
+  SendTarget: {
+    ALL_WINDOWS: 'ALL_WINDOWS'
+  }
+}))
+
+describe('ProviderDbLoader', () => {
+  let tempRoot: string
+  let appRoot: string
+  let userDataRoot: string
+
+  const importLoader = async () => {
+    const mod = await import('../../../../src/main/presenter/configPresenter/providerDbLoader')
+    return mod.ProviderDbLoader
+  }
+
+  const getCacheDir = () => path.join(userDataRoot, 'provider-db')
+  const getCacheFile = () => path.join(getCacheDir(), 'providers.json')
+  const getMetaFile = () => path.join(getCacheDir(), 'meta.json')
+
+  const createAggregate = (providerIds: string[]) => ({
+    providers: Object.fromEntries(
+      providerIds.map((providerId) => [
+        providerId,
+        {
+          id: providerId,
+          name: providerId,
+          models: [
+            {
+              id: `${providerId}-model`
+            }
+          ]
+        }
+      ])
+    )
+  })
+
+  const writeBuiltInDb = (aggregate: Record<string, unknown>) => {
+    const modelDbDir = path.join(appRoot, 'resources', 'model-db')
+    fs.mkdirSync(modelDbDir, { recursive: true })
+    fs.writeFileSync(path.join(modelDbDir, 'providers.json'), JSON.stringify(aggregate), 'utf-8')
+  }
+
+  const writeCachedDb = (aggregate: Record<string, unknown>) => {
+    fs.mkdirSync(getCacheDir(), { recursive: true })
+    fs.writeFileSync(getCacheFile(), JSON.stringify(aggregate), 'utf-8')
+  }
+
+  const writeMeta = (meta: {
+    sourceUrl: string
+    etag?: string
+    lastUpdated: number
+    ttlHours: number
+    lastAttemptedAt?: number
+  }) => {
+    fs.mkdirSync(getCacheDir(), { recursive: true })
+    fs.writeFileSync(getMetaFile(), JSON.stringify(meta), 'utf-8')
+  }
+
+  const readMeta = () => JSON.parse(fs.readFileSync(getMetaFile(), 'utf-8'))
+
+  beforeEach(() => {
+    tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'deepchat-provider-db-'))
+    appRoot = path.join(tempRoot, 'app-root')
+    userDataRoot = path.join(tempRoot, 'user-data')
+    fs.mkdirSync(appRoot, { recursive: true })
+    fs.mkdirSync(userDataRoot, { recursive: true })
+
+    state.getPath.mockImplementation((name: string) => {
+      if (name === 'userData') return userDataRoot
+      return userDataRoot
+    })
+    state.getAppPath.mockReturnValue(appRoot)
+    state.send.mockReset()
+    vi.unstubAllGlobals()
+    delete process.env.PROVIDER_DB_TTL_HOURS
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+    delete process.env.PROVIDER_DB_TTL_HOURS
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('initializes from cache and still triggers a startup refresh when cache is fresh', async () => {
+    writeBuiltInDb(createAggregate(['builtin']))
+    writeCachedDb(createAggregate(['openai']))
+    const now = Date.now()
+    writeMeta({
+      sourceUrl: 'https://example.com/provider-db.json',
+      etag: '"etag-1"',
+      lastUpdated: now,
+      lastAttemptedAt: now,
+      ttlHours: 4
+    })
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      status: 304,
+      ok: false,
+      headers: {
+        get: vi.fn().mockReturnValue('"etag-1"')
+      }
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const ProviderDbLoader = await importLoader()
+    const loader = new ProviderDbLoader()
+
+    await loader.initialize()
+
+    expect(loader.getDb()?.providers).toHaveProperty('openai')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(state.send).toHaveBeenCalledWith('provider-db:loaded', 'ALL_WINDOWS', {
+      providersCount: 1
+    })
+  })
+
+  it('skips non-forced refreshes within the default 4-hour TTL', async () => {
+    writeCachedDb(createAggregate(['openai']))
+    const now = Date.now()
+    writeMeta({
+      sourceUrl: 'https://example.com/provider-db.json',
+      lastUpdated: now - 5_000,
+      lastAttemptedAt: now - 5_000,
+      ttlHours: 4
+    })
+
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    const ProviderDbLoader = await importLoader()
+    const loader = new ProviderDbLoader()
+
+    const result = await loader.refreshIfNeeded(false)
+
+    expect(result.status).toBe('skipped')
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('treats 304 responses as fresh and avoids another fetch inside the TTL window', async () => {
+    writeCachedDb(createAggregate(['openai']))
+    const staleTimestamp = Date.now() - 10 * 3600 * 1000
+    writeMeta({
+      sourceUrl: 'https://example.com/provider-db.json',
+      etag: '"etag-2"',
+      lastUpdated: staleTimestamp,
+      lastAttemptedAt: staleTimestamp,
+      ttlHours: 4
+    })
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      status: 304,
+      ok: false,
+      headers: {
+        get: vi.fn().mockReturnValue('"etag-2"')
+      }
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const ProviderDbLoader = await importLoader()
+    const loader = new ProviderDbLoader()
+
+    const result = await loader.refreshIfNeeded(true)
+
+    expect(result.status).toBe('not-modified')
+    expect(result.lastUpdated).toBe(staleTimestamp)
+
+    const meta = readMeta()
+    expect(meta.lastUpdated).toBe(staleTimestamp)
+    expect(meta.lastAttemptedAt).toBeGreaterThan(staleTimestamp)
+
+    fetchMock.mockClear()
+    const nextResult = await loader.refreshIfNeeded(false)
+    expect(nextResult.status).toBe('skipped')
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('writes refreshed provider data and emits an update event on success', async () => {
+    writeCachedDb(createAggregate(['openai']))
+
+    const refreshedAggregate = createAggregate(['openai', 'anthropic'])
+    const fetchMock = vi.fn().mockResolvedValue({
+      status: 200,
+      ok: true,
+      headers: {
+        get: vi.fn().mockReturnValue('"etag-3"')
+      },
+      text: vi.fn().mockResolvedValue(JSON.stringify(refreshedAggregate))
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const ProviderDbLoader = await importLoader()
+    const loader = new ProviderDbLoader()
+
+    const result = await loader.refreshIfNeeded(true)
+
+    expect(result.status).toBe('updated')
+    expect(result.providersCount).toBe(2)
+    expect(loader.getDb()?.providers).toHaveProperty('anthropic')
+    expect(state.send).toHaveBeenCalledWith('provider-db:updated', 'ALL_WINDOWS', {
+      providersCount: 2,
+      lastUpdated: expect.any(Number)
+    })
+  })
+
+  it('returns an error result and preserves the existing cache when refresh fails', async () => {
+    const cachedAggregate = createAggregate(['openai'])
+    writeCachedDb(cachedAggregate)
+    const now = Date.now() - 10 * 3600 * 1000
+    writeMeta({
+      sourceUrl: 'https://example.com/provider-db.json',
+      lastUpdated: now,
+      lastAttemptedAt: now,
+      ttlHours: 4
+    })
+
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network down')))
+
+    const ProviderDbLoader = await importLoader()
+    const loader = new ProviderDbLoader()
+
+    const result = await loader.refreshIfNeeded(true)
+
+    expect(result.status).toBe('error')
+    expect(result.message).toBe('network down')
+    expect(JSON.parse(fs.readFileSync(getCacheFile(), 'utf-8'))).toEqual(cachedAggregate)
+    expect(readMeta().lastAttemptedAt).toBeGreaterThan(now)
+  })
+})
diff --git a/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts b/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts
index 762a2de47..19d89e955 100644
--- a/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts
+++ b/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts
@@ -1,5 +1,9 @@
+import { EventEmitter } from 'events'
+import * as fs from 'fs'
 import path from 'path'
 import { describe, expect, it, vi } from 'vitest'
+import spawn from 'cross-spawn'
+import * as shellEnvHelper from '@/lib/agentRuntime/shellEnvHelper'
 import {
   AcpProcessManager,
   parseLoadSessionCapability
@@ -21,6 +25,31 @@ vi.mock('electron', () => ({
   }
 }))
 
+vi.mock('cross-spawn', () => ({
+  default: vi.fn()
+}))
+
+vi.mock('@/lib/agentRuntime/shellEnvHelper', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/lib/agentRuntime/shellEnvHelper')>()
+  return {
+    ...actual,
+    getShellEnvironment: vi.fn().mockResolvedValue({ PATH: '/shell/bin' })
+  }
+})
+
+class MockStream extends EventEmitter {}
+
+class MockSpawnedChild extends EventEmitter {
+  stdout = new MockStream()
+  stderr = new MockStream()
+  stdin = new MockStream()
+  pid = 1234
+  killed = false
+  exitCode = null
+  signalCode = null
+  kill = vi.fn(() => true)
+}
+
 describe('parseLoadSessionCapability', () => {
   it('parses boolean capability from initialize result', () => {
     expect(parseLoadSessionCapability({ agentCapabilities: { loadSession: true } })).toBe(true)
@@ -223,4 +252,86 @@ describe('AcpProcessManager config cache fallback', () => {
       })
     )
   })
+
+  it('keeps explicit PATH overrides ahead of bundled runtime and shell PATH', async () => {
+    const originalPath = process.env.PATH
+    process.env.PATH = '/usr/bin:/bin'
+
+    try {
+      const manager = new AcpProcessManager({
+        providerId: 'acp',
+        resolveLaunchSpec: vi.fn().mockResolvedValue({
+          agentId: 'agent-1',
+          source: 'manual',
+          distributionType: 'npx',
+          command: 'agent',
+          args: [],
+          env: {
+            PATH: '/launch/bin',
+            LAUNCH_ONLY: '1'
+          },
+          cwd: '/tmp/workspace'
+        }),
+        getAgentState: vi.fn().mockResolvedValue({
+          envOverride: {
+            PATH: '/user/bin',
+            USER_ONLY: '1'
+          }
+        })
+      })
+
+      const child = new MockSpawnedChild()
+      vi.mocked(spawn).mockReturnValue(child as never)
+      vi.spyOn(shellEnvHelper, 'getShellEnvironment').mockResolvedValue({
+        PATH: '/shell/bin'
+      })
+      vi.spyOn((manager as any).runtimeHelper, 'initializeRuntimes').mockImplementation(() => {})
+      vi.spyOn((manager as any).runtimeHelper, 'expandPath').mockImplementation(
+        (value: string) => value
+      )
+      vi.spyOn((manager as any).runtimeHelper, 'replaceWithRuntimeCommand').mockImplementation(
+        (value: string) => value
+      )
+      vi.spyOn((manager as any).runtimeHelper, 'prependBundledRuntimeToEnv').mockImplementation(
+        (env: Record<string, string>) => ({
+          ...env,
+          PATH: ['/runtime/bin', env.PATH].filter(Boolean).join(':')
+        })
+      )
+      vi.spyOn((manager as any).runtimeHelper, 'getDefaultPaths').mockReturnValue(['/default/bin'])
+      vi.spyOn((manager as any).runtimeHelper, 'getUvRuntimePath').mockReturnValue('/runtime/bin')
+      vi.spyOn((manager as any).runtimeHelper, 'getNodeRuntimePath').mockReturnValue(null)
+      vi.spyOn((manager as any).runtimeHelper, 'isInstalledInSystemDirectory').mockReturnValue(
+        false
+      )
+      vi.spyOn((manager as any).runtimeHelper, 'getUserNpmPrefix').mockReturnValue(null)
+      vi.spyOn(fs, 'existsSync').mockReturnValue(true)
+
+      await (manager as any).spawnAgentProcess(
+        {
+          id: 'agent-1',
+          name: 'Agent One',
+          command: 'agent'
+        },
+        '/tmp/workspace'
+      )
+
+      expect(spawn).toHaveBeenCalledWith(
+        'agent',
+        [],
+        expect.objectContaining({
+          cwd: '/tmp/workspace',
+          env: expect.objectContaining({
+            LAUNCH_ONLY: '1',
+            USER_ONLY: '1',
+            ACP_IDE: 'deepchat',
+            DEEPCHAT_ACP_AGENT_ID: 'agent-1',
+            PATH: expect.stringContaining('/user/bin:/launch/bin:/runtime/bin:/shell/bin')
+          })
+        })
+      )
+    } finally {
+      process.env.PATH = originalPath
+    }
+  })
 })
diff --git a/test/main/presenter/skillPresenter/skillExecutionService.test.ts b/test/main/presenter/skillPresenter/skillExecutionService.test.ts
index 713b1669a..0c528fe0e 100644
--- a/test/main/presenter/skillPresenter/skillExecutionService.test.ts
+++ b/test/main/presenter/skillPresenter/skillExecutionService.test.ts
@@ -15,10 +15,16 @@ vi.mock('electron', () => ({
   }
 }))
 
-vi.mock('../../../../src/main/lib/agentRuntime/shellEnvHelper', () => ({
-  getShellEnvironment: vi.fn().mockResolvedValue({ PATH: '/shell/bin' }),
-  getUserShell: vi.fn().mockReturnValue({ shell: '/bin/zsh', args: ['-c'] })
-}))
+vi.mock('../../../../src/main/lib/agentRuntime/shellEnvHelper', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../../../../src/main/lib/agentRuntime/shellEnvHelper')>()
+
+  return {
+    ...actual,
+    getShellEnvironment: vi.fn().mockResolvedValue({ PATH: '/shell/bin' }),
+    getUserShell: vi.fn().mockReturnValue({ shell: '/bin/zsh', args: ['-c'] })
+  }
+})
 
 vi.mock('../../../../src/main/lib/agentRuntime/rtkRuntimeService', () => ({
   rtkRuntimeService: {
@@ -116,7 +122,7 @@ describe('SkillExecutionService', () => {
     )
 
     expect(plan.cwd).toBe('/workspace/session')
-    expect(plan.env.PATH).toBe('/shell/bin')
+    expect(plan.env.PATH).toContain('/shell/bin')
     expect(plan.env.API_KEY).toBe('secret')
     expect(plan.env.SKILL_ROOT).toBe('/skills/ocr')
     expect(plan.env.DEEPCHAT_SKILL_ROOT).toBe('/skills/ocr')
diff --git a/test/main/presenter/toolPresenter/agentTools/agentBashHandler.test.ts b/test/main/presenter/toolPresenter/agentTools/agentBashHandler.test.ts
index 23cbf822c..f3a0ae9b0 100644
--- a/test/main/presenter/toolPresenter/agentTools/agentBashHandler.test.ts
+++ b/test/main/presenter/toolPresenter/agentTools/agentBashHandler.test.ts
@@ -1,6 +1,7 @@
 import path from 'path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { backgroundExecSessionManager } from '../../../../../src/main/lib/agentRuntime/backgroundExecSessionManager'
+import * as shellEnvHelper from '../../../../../src/main/lib/agentRuntime/shellEnvHelper'
 import { AgentBashHandler } from '../../../../../src/main/presenter/toolPresenter/agentTools/agentBashHandler'
 
 describe('AgentBashHandler', () => {
@@ -138,6 +139,28 @@ describe('AgentBashHandler', () => {
     expect(result.output).toContain('Timed out')
   })
 
+  it('builds fallback shell env when RTK settings are unavailable', async () => {
+    const handler = new AgentBashHandler(['/workspace'])
+
+    vi.spyOn(shellEnvHelper, 'getShellEnvironment').mockResolvedValue({
+      PATH: '/shell/bin:/usr/local/bin'
+    })
+
+    const prepared = await (handler as never).prepareCommand('which node', {
+      PATH: '/custom/bin',
+      CUSTOM_FLAG: '1'
+    })
+
+    expect(prepared.rtkApplied).toBe(false)
+    expect(prepared.rtkMode).toBe('bypass')
+    expect(prepared.env.CUSTOM_FLAG).toBe('1')
+    expect(prepared.env.PATH.split(':').slice(0, 3)).toEqual([
+      '/custom/bin',
+      '/shell/bin',
+      '/usr/local/bin'
+    ])
+  })
+
   it('keeps background execution on the bypass path without foreground retry', async () => {
     const originalCommand = 'find . -type f -name "*.ts" -o -name "*.vue"'
     const handler = new AgentBashHandler(['/workspace'])
diff --git a/test/renderer/components/DataSettings.test.ts b/test/renderer/components/DataSettings.test.ts
new file mode 100644
index 000000000..d715e2fe8
--- /dev/null
+++ b/test/renderer/components/DataSettings.test.ts
@@ -0,0 +1,232 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, nextTick, reactive } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+
+const buttonStub = defineComponent({
+  name: 'Button',
+  props: {
+    disabled: {
+      type: Boolean,
+      default: false
+    }
+  },
+  emits: ['click'],
+  template: '<button :disabled="disabled" @click="$emit(\'click\')"><slot /></button>'
+})
+
+const passthroughStub = (name: string) =>
+  defineComponent({
+    name,
+    template: '<div><slot /></div>'
+  })
+
+const setup = async () => {
+  vi.resetModules()
+
+  const toast = vi.fn()
+  const syncStore = reactive({
+    syncEnabled: true,
+    syncFolderPath: '/tmp/deepchat-sync',
+    lastSyncTime: 0,
+    isBackingUp: false,
+    isImporting: false,
+    importResult: null,
+    backups: [] as Array<{ fileName: string; createdAt: number; size: number }>,
+    initialize: vi.fn().mockResolvedValue(undefined),
+    selectSyncFolder: vi.fn(),
+    openSyncFolder: vi.fn(),
+    refreshBackups: vi.fn().mockResolvedValue(undefined),
+    startBackup: vi.fn().mockResolvedValue(null),
+    importData: vi.fn().mockResolvedValue(null),
+    clearImportResult: vi.fn(),
+    setSyncEnabled: vi.fn(),
+    setSyncFolderPath: vi.fn()
+  })
+
+  const presenterMocks = {
+    configPresenter: {
+      refreshProviderDb: vi.fn().mockResolvedValue({
+        status: 'updated',
+        lastUpdated: Date.now(),
+        providersCount: 1
+      })
+    },
+    devicePresenter: {
+      resetDataByType: vi.fn().mockResolvedValue(undefined)
+    },
+    yoBrowserPresenter: {
+      clearSandboxData: vi.fn().mockResolvedValue(undefined)
+    }
+  }
+
+  vi.doMock('@/stores/sync', () => ({
+    useSyncStore: () => syncStore
+  }))
+  vi.doMock('@/stores/language', () => ({
+    useLanguageStore: () => ({
+      dir: 'ltr'
+    })
+  }))
+  vi.doMock('@/composables/usePresenter', () => ({
+    usePresenter: (name: keyof typeof presenterMocks) => presenterMocks[name]
+  }))
+  vi.doMock('@/components/use-toast', () => ({
+    useToast: () => ({
+      toast
+    })
+  }))
+  vi.doMock('vue-i18n', () => ({
+    useI18n: () => ({
+      t: (key: string) => key
+    })
+  }))
+  vi.doMock('pinia', async () => {
+    const vue = await vi.importActual<typeof import('vue')>('vue')
+    return {
+      storeToRefs: () => ({
+        backups: vue.toRef(syncStore, 'backups')
+      })
+    }
+  })
+
+  const DataSettings = (await import('../../../src/renderer/settings/components/DataSettings.vue'))
+    .default
+
+  const wrapper = mount(DataSettings, {
+    global: {
+      stubs: {
+        ScrollArea: passthroughStub('ScrollArea'),
+        Icon: true,
+        Dialog: passthroughStub('Dialog'),
+        DialogContent: passthroughStub('DialogContent'),
+        DialogDescription: passthroughStub('DialogDescription'),
+        DialogFooter: passthroughStub('DialogFooter'),
+        DialogHeader: passthroughStub('DialogHeader'),
+        DialogTitle: passthroughStub('DialogTitle'),
+        DialogTrigger: passthroughStub('DialogTrigger'),
+        AlertDialog: passthroughStub('AlertDialog'),
+        AlertDialogAction: passthroughStub('AlertDialogAction'),
+        AlertDialogCancel: passthroughStub('AlertDialogCancel'),
+        AlertDialogContent: passthroughStub('AlertDialogContent'),
+        AlertDialogDescription: passthroughStub('AlertDialogDescription'),
+        AlertDialogFooter: passthroughStub('AlertDialogFooter'),
+        AlertDialogHeader: passthroughStub('AlertDialogHeader'),
+        AlertDialogTitle: passthroughStub('AlertDialogTitle'),
+        AlertDialogTrigger: passthroughStub('AlertDialogTrigger'),
+        Button: buttonStub,
+        Input: defineComponent({ name: 'Input', template: '<input />' }),
+        Switch: defineComponent({ name: 'Switch', template: '<input type="checkbox" />' }),
+        RadioGroup: passthroughStub('RadioGroup'),
+        RadioGroupItem: passthroughStub('RadioGroupItem'),
+        Label: passthroughStub('Label'),
+        Separator: passthroughStub('Separator'),
+        Select: passthroughStub('Select'),
+        SelectContent: passthroughStub('SelectContent'),
+        SelectItem: passthroughStub('SelectItem'),
+        SelectTrigger: passthroughStub('SelectTrigger'),
+        SelectValue: passthroughStub('SelectValue')
+      }
+    }
+  })
+
+  await flushPromises()
+
+  return {
+    wrapper,
+    toast,
+    syncStore,
+    presenterMocks
+  }
+}
+
+const findRefreshButton = (wrapper: ReturnType<typeof mount>) => {
+  const button = wrapper
+    .findAll('button')
+    .find((item) => item.text().includes('settings.data.modelConfigUpdate'))
+
+  if (!button) {
+    throw new Error('Refresh provider DB button not found')
+  }
+
+  return button
+}
+
+describe('DataSettings', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('calls refreshProviderDb, shows loading state, then shows an updated toast', async () => {
+    const { wrapper, toast, presenterMocks } = await setup()
+
+    let resolveRefresh:
+      | ((value: { status: string; lastUpdated: number; providersCount: number }) => void)
+      | null = null
+    presenterMocks.configPresenter.refreshProviderDb.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveRefresh = resolve
+      })
+    )
+
+    await findRefreshButton(wrapper).trigger('click')
+    await nextTick()
+
+    const loadingButton = findRefreshButton(wrapper)
+    expect(loadingButton.attributes('disabled')).toBeDefined()
+    expect(loadingButton.text()).toContain('settings.data.modelConfigUpdate.updating')
+
+    resolveRefresh?.({
+      status: 'updated',
+      lastUpdated: Date.now(),
+      providersCount: 3
+    })
+    await flushPromises()
+
+    expect(presenterMocks.configPresenter.refreshProviderDb).toHaveBeenCalledWith(true)
+    expect(toast).toHaveBeenCalledWith({
+      title: 'settings.data.modelConfigUpdate.updatedTitle',
+      description: 'settings.data.modelConfigUpdate.updatedDescription',
+      duration: 4000
+    })
+  })
+
+  it('shows an up-to-date toast when upstream metadata has not changed', async () => {
+    const { wrapper, toast, presenterMocks } = await setup()
+
+    presenterMocks.configPresenter.refreshProviderDb.mockResolvedValueOnce({
+      status: 'not-modified',
+      lastUpdated: Date.now(),
+      providersCount: 2
+    })
+
+    await findRefreshButton(wrapper).trigger('click')
+    await flushPromises()
+
+    expect(toast).toHaveBeenCalledWith({
+      title: 'settings.data.modelConfigUpdate.upToDateTitle',
+      description: 'settings.data.modelConfigUpdate.upToDateDescription',
+      duration: 4000
+    })
+  })
+
+  it('shows a destructive toast when refreshing provider metadata fails', async () => {
+    const { wrapper, toast, presenterMocks } = await setup()
+
+    presenterMocks.configPresenter.refreshProviderDb.mockResolvedValueOnce({
+      status: 'error',
+      lastUpdated: null,
+      providersCount: 1,
+      message: 'network down'
+    })
+
+    await findRefreshButton(wrapper).trigger('click')
+    await flushPromises()
+
+    expect(toast).toHaveBeenCalledWith({
+      title: 'settings.data.modelConfigUpdate.failedTitle',
+      description: 'settings.data.modelConfigUpdate.failedDescription',
+      variant: 'destructive',
+      duration: 4000
+    })
+  })
+})
diff --git a/test/renderer/components/SuggestionList.test.ts b/test/renderer/components/SuggestionList.test.ts
index 1eca81308..c5818ab41 100644
--- a/test/renderer/components/SuggestionList.test.ts
+++ b/test/renderer/components/SuggestionList.test.ts
@@ -16,6 +16,29 @@ describe('SuggestionList', () => {
     HTMLElement.prototype.scrollIntoView = vi.fn()
   })
 
+  it('renders command suggestions with a command icon instead of a slash tag', () => {
+    const items: SuggestionListItem[] = [
+      {
+        id: 'command:plan',
+        label: '/plan',
+        category: 'command',
+        payload: { name: 'plan', description: '', input: null }
+      }
+    ]
+
+    const wrapper = mount(SuggestionList, {
+      props: {
+        items,
+        query: '',
+        command: vi.fn()
+      }
+    })
+
+    expect(wrapper.find('[data-icon="lucide:command"]').exists()).toBe(true)
+    expect(wrapper.text()).toContain('/plan')
+    expect(wrapper.text().match(/\//g) ?? []).toHaveLength(1)
+  })
+
   it('renders the full upstream item list without truncating', () => {
     const items = buildItems(25)