@goodandready/dsh-clinebot 0.5.13 → 0.5.16

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to `@goodandready/dsh-clinebot` will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.16] - 2026-10-04
+
+### Fixed
+- **Dedicated Loopback Proxy Server & DSH Desktop 2.x Compatibility (Issues GH #12, #195)**: Resolved issue where `DesktopWebServer` on DSH Desktop 2.x in advanced shell mode rejected all internal loopback requests from the Node.js host process with HTTP 403 `forbidden` (lacking `x-dsh-desktop-renderer`). Decoupled proxy execution by spinning up an isolated dedicated HTTP loopback server listening on `127.0.0.1` (ephemeral port), completely bypassing host route fencing and restoring transparent proxy routing, multi-account failover, and telemetry on Desktop installations.
+- **Desktop Fence Self-Detection & Direct Upstream Fallback (Issues GH #12, #195)**: Added `detectHostWebServerFence` probe that detects `DesktopWebServer` 403 `forbidden` signatures on host ports; automatically falls back to direct upstream endpoint (`baseUrl`) if the dedicated loopback server is unavailable or fails to bind, guaranteeing requests never stall with `AUTH 403`.
+- **Proxy Mode UI Toggle in Diagnostics Section (Issues GH #12, #195)**: Added an explicit user-facing toggle in the Diagnostics & Auto-Registration settings card (`src/client/components/diag-section.js`) allowing users to easily switch between Transparent Loopback Proxy Mode (failover & telemetry) and Direct Mode (direct upstream connection) directly from the Web & Desktop UI.
+
+## [0.5.15] - 2026-10-02
+
+### Fixed
+- **Atomic Catalog Snapshot Reset on Settings Persistence (Issue #192)**: In `settingsApi.update` and `settingsApi.replace`, defer invalidating the verified model catalog snapshot (`resetCatalogSnapshot()`) and updating `lastCatalogIdentity` until after persistence to the DSH settings service completes successfully. If settings persistence fails (e.g. revision conflict or rejection), local in-memory dynamic models and plan synchronization timestamp are strictly preserved, preventing catalog loss when endpoint and credentials remain unchanged.
+
+## [0.5.14] - 2026-10-02
+
+### Fixed
+- **Catalog Identity Lifecycle on Endpoint & Primary Credential Switch (Issue #168)**: Unified catalog invalidation under an identity contract: the verified catalog and plan synchronization timestamp strictly belong to the identity tuple (`baseUrl::activeAccount::apiKeyEnv`). Changing primary credential reference (`apiKeyEnv`) or provider endpoint (`baseUrl`) — via native Cosmokit volatile updates or `PUT /dsh-clinebot/config` — immediately resets `dynamicModels = []`, `planSyncedAt = 0`, and purges both usage and probe caches (`clearUsageCache()`, `clearProbeCache()`), preventing foreign or unverified model snapshots from persisting across endpoint or credential changes.
+
 ## [0.5.13] - 2026-10-02
 
 ### Fixed

package/README.md

@@ -229,6 +229,8 @@ All endpoints are registered under `/dsh-clinebot/*` and protected against untru
 * `POST /dsh-clinebot/v1/chat/completions` — Transparent local proxy supporting streaming SSE and non-streaming responses, Bearer token authentication, sticky session affinity with least-used quota allocation, body read watchdog (`streamIdleTimeoutMs`), and automatic 429 failover.
 * `GET /dsh-clinebot/v1/models` — OpenAI-compatible catalog listing all active plan and custom models.
 
+> **DSH Desktop 2.x & Headless Environments**: The loopback proxy binds an isolated loopback HTTP server on `127.0.0.1` (ephemeral port), completely bypassing `DesktopWebServer` renderer fences (`x-dsh-desktop-renderer`). Automated fence detection (`detectHostWebServerFence`) falls back to direct upstream connection if the loopback server is restricted, and proxy mode can be directly toggled via the Diagnostics settings card.
+
 ---
 
 ## Visual verification

package/README.ru.md

@@ -226,6 +226,8 @@ dsh-clinebot:
 * `POST /dsh-clinebot/v1/chat/completions` — Прозрачный локальный прокси с поддержкой SSE и нестриминговых ответов, Bearer-аутентификацией, сессионной липкостью и least-used распределением квот, контролем дедлайнов (`streamIdleTimeoutMs`) и автоматическим 429 failover.
 * `GET /dsh-clinebot/v1/models` — Каталог моделей в стандарте OpenAI API.
 
+> **DSH Desktop 2.x и автономные окружения**: Прокси поднимает изолированный выделенный HTTP-сервер на `127.0.0.1` (эфемеридный порт), полностью обходя сетевые экраны `DesktopWebServer` (`x-dsh-desktop-renderer`). Встроенный детектор защитных экранов (`detectHostWebServerFence`) автоматически переключает провайдер на прямое соединение с upstream при ограничении loopback-порта, а режим прокси можно переключать напрямую в карточке «Диагностика» в UI.
+
 ---
 
 ## 🧪 Тестирование

package/README.zh.md

@@ -228,6 +228,8 @@ dsh-clinebot:
 * `POST /dsh-clinebot/v1/chat/completions` — 本地透明代理，支持 SSE 流式与完整响应、会话粘性路由、最低用量负载均衡、响应体超时防护 (`streamIdleTimeoutMs`) 以及 429 自动故障转移。
 * `GET /dsh-clinebot/v1/models` — 符合 OpenAI API 规范的模型列表。
 
+> **DSH Desktop 2.x 与无界面环境**：环回代理在 `127.0.0.1` 绑定独立的专用 HTTP 服务（临时端口），彻底绕过桌面端路由防护 (`DesktopWebServer` 的 `x-dsh-desktop-renderer` 限制）。内置防护检测机制 (`detectHostWebServerFence`) 在环回端口受限时自动回退为直连模式，用户亦可在设置页的“诊断”模块中直接切换代理模式。
+
 ---
 
 ## 🧪 测试

package/lib/client.js

@@ -178,6 +178,10 @@ const en = {
       'diag.unregister_btn': 'Unregister from DSH',
       'diag.unregistering': 'Removing…',
       'diag.unregistered_msg': 'Provider removed from DSH Models',
+      'diag.proxy_title': 'Transparent Loopback Proxy',
+      'diag.proxy_desc': 'Enables multi-account failover, sticky sessions, and telemetry via local loopback proxy. Disable to connect directly to upstream endpoint.',
+      'diag.proxy_enabled': 'Proxy Mode Enabled (Failover & Telemetry Active)',
+      'diag.proxy_disabled': 'Direct Mode (Direct Upstream, No Proxy)',
       'update.available': 'Update available: v{latestVersion} (current: v{currentVersion})',
       'update.btn': 'Update Now',
       'update.updating': 'Updating…',
@@ -327,6 +331,10 @@ const en = {
       'diag.unregister_btn': '从 DSH 注销该服务',
       'diag.unregistering': '正在注销…',
       'diag.unregistered_msg': '已从 DSH 模型注册表中移除',
+      'diag.proxy_title': '本地透明回环代理',
+      'diag.proxy_desc': '通过本地回环代理支持多账户故障转移、会话保持与实时统计。关闭后直连上游端点。',
+      'diag.proxy_enabled': '代理模式已开启（支持故障转移与遥测）',
+      'diag.proxy_disabled': '直连模式（直接连接上游，无本地代理）',
       'update.available': '发现新版本 v{latestVersion}（当前版本 v{currentVersion}）',
       'update.btn': '立即更新',
       'update.updating': '正在更新…',
@@ -1835,12 +1843,72 @@ function StatsSection({ status, onResetStats, busy, t }) {
 }
 
 // --- src/client/components/diag-section.js ---
-function DiagSection({ keyPresent, isRegistered, busy, smokeResult, handleSmoke, handleUnregister, handleRegister, t }) {
+function DiagSection({
+  keyPresent,
+  isRegistered,
+  busy,
+  smokeResult,
+  handleSmoke,
+  handleUnregister,
+  handleRegister,
+  proxyMode,
+  onToggleProxy,
+  t,
+}) {
   return React.createElement(
     'div',
     { className: 'cb-section-card' },
     React.createElement('div', { className: 'cb-section-title' }, t('diag.title')),
     React.createElement('div', { className: 'cb-section-desc' }, t('diag.desc')),
+    React.createElement(
+      'div',
+      {
+        style: {
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          padding: '10px 14px',
+          background: 'var(--dsw-alias-bg-layer-2)',
+          borderRadius: '8px',
+          border: '1px solid var(--dsw-alias-border-l2)',
+        },
+      },
+      React.createElement(
+        'div',
+        { style: { display: 'flex', flexDirection: 'column', gap: '3px' } },
+        React.createElement(
+          'span',
+          { style: { fontSize: '13px', fontWeight: 600, color: 'var(--dsw-alias-label-primary)' } },
+          t('diag.proxy_title')
+        ),
+        React.createElement(
+          'span',
+          { style: { fontSize: '12px', color: 'var(--dsw-alias-label-secondary)' } },
+          t('diag.proxy_desc')
+        )
+      ),
+      React.createElement(
+        'label',
+        { style: { display: 'inline-flex', alignItems: 'center', gap: '8px', cursor: 'pointer', whiteSpace: 'nowrap' } },
+        React.createElement('input', {
+          type: 'checkbox',
+          checked: !!proxyMode,
+          disabled: !!busy,
+          onChange: (e) => onToggleProxy && onToggleProxy(e.target.checked),
+        }),
+        React.createElement(
+          'span',
+          {
+            style: {
+              fontSize: '13px',
+              fontWeight: 500,
+              color: proxyMode ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-label-secondary)',
+            },
+          },
+          proxyMode ? t('diag.proxy_enabled') : t('diag.proxy_disabled')
+        )
+      )
+    ),
     React.createElement(
       'div',
       { className: 'cb-row' },
@@ -1901,8 +1969,7 @@ function SettingsPage(props) {
   const [status, setStatus] = React.useState(null)
   const [draft, setDraft] = React.useState(null)
   const [busy, setBusy] = React.useState('')
-  const [err, setErr] = React.useState('')
-  const [msg, setMsg] = React.useState('')
+  const [err, setErr] = React.useState(''), [msg, setMsg] = React.useState('')
   const [smokeResult, setSmokeResult] = React.useState(null)
 
   const [updateState, setUpdateState] = React.useState({
@@ -1911,8 +1978,7 @@ function SettingsPage(props) {
     error: '', notice: '',
   })
 
-  const [apiKeyInput, setApiKeyInput] = React.useState('')
-  const [showKey, setShowKey] = React.useState(false)
+  const [apiKeyInput, setApiKeyInput] = React.useState(''), [showKey, setShowKey] = React.useState(false)
 
   React.useEffect(() => { ensureCss() }, [])
 
@@ -1930,9 +1996,7 @@ function SettingsPage(props) {
     setDraft(data.config || {})
   }, [])
 
-  React.useEffect(() => {
-    load().catch((e) => setErr(String(e.message || e)))
-  }, [load])
+  React.useEffect(() => { load().catch((e) => setErr(String(e.message || e))) }, [load])
 
   const checkUpdate = React.useCallback(async () => {
     setUpdateState((s) => ({ ...s, checking: true, status: 'checking', error: '' }))
@@ -2202,11 +2266,7 @@ function SettingsPage(props) {
 
   const debounceTimerRef = typeof React.useRef === 'function' ? React.useRef(null) : { current: null }
 
-  React.useEffect(() => {
-    return () => {
-      if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current)
-    }
-  }, [])
+  React.useEffect(() => () => { if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current) }, [])
 
   function debounceSaveDisabledModels(nextDisabled, previousDisabled) {
     if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current)
@@ -2368,8 +2428,7 @@ function SettingsPage(props) {
       onConfigUpdate: handleConfigPatch,
       onUpdateReasoningEffort: (modelId, effort) => {
         const next = { ...(draft?.modelReasoningDefaults || {}) }
-        if (!effort) delete next[modelId]
-        else next[modelId] = effort
+        if (!effort) delete next[modelId]; else next[modelId] = effort
         handleConfigPatch({ modelReasoningDefaults: next })
       },
       t,
@@ -2387,6 +2446,8 @@ function SettingsPage(props) {
       handleSmoke,
       handleUnregister,
       handleRegister,
+      proxyMode: draft?.proxyMode !== false,
+      onToggleProxy: (val) => handleConfigPatch({ proxyMode: val }),
       t,
     })
   )

package/lib/index.js

@@ -23,6 +23,7 @@ import { registerAccountsRoutes } from './routes/accounts.js'
 import { registerModelsRoutes } from './routes/models.js'
 import { registerAuthRoutes } from './routes/auth.js'
 import { registerProxyRoutes } from './routes/proxy.js'
+import { startLoopbackProxyServer, stopLoopbackProxyServer } from './proxy-server.js'
 import { registerSlashCommand } from './slash-command.js'
 import { recordUsage, loadStats, flushStats, resolvePath, switchStatsStorage } from './stats-storage.js'
 
@@ -82,6 +83,11 @@ export function apply(ctx, config) {
         await removePiAiProvider(ctx)
         return
       }
+      if (pub.proxyMode !== false && (ctx?.webServer || typeof ctx?.get === 'function')) {
+        await startLoopbackProxyServer(ctx, routeEnv)
+      } else {
+        await stopLoopbackProxyServer()
+      }
       const activeKey = await resolveActiveAccountKey(ctx, cfg)
       if (activeKey.value) {
         await upsertPiAiProvider(ctx, cfg, pub.enabledModels)
@@ -106,25 +112,35 @@ export function apply(ctx, config) {
     }
   }
 
-  let lastActiveAccount = publicConfig(live()).activeAccount
+  const normalizeEndpoint = (url) => String(url || '').trim().replace(/\/+$/, '')
+  const getCatalogIdentity = (cfg) => {
+    const pub = publicConfig(cfg)
+    return `${normalizeEndpoint(pub.baseUrl)}::${String(pub.activeAccount || '').trim()}::${String(pub.apiKeyEnv || '').trim()}`
+  }
+
+  let lastCatalogIdentity = getCatalogIdentity(live())
+  const resetCatalogSnapshot = () => {
+    try {
+      if (currentConfig && typeof currentConfig === 'object') {
+        currentConfig.dynamicModels = []
+        currentConfig.planSyncedAt = 0
+      }
+    } catch {
+      /* ignore read-only or frozen */
+    }
+    overrides.dynamicModels = []
+    overrides.planSyncedAt = 0
+    clearUsageCache()
+    clearProbeCache()
+  }
+
   if (typeof ctx?.on === 'function') {
     ctx.on('loader/volatile-update', () => {
       const liveCfg = live()
-      const currentActive = publicConfig(liveCfg).activeAccount
-      if (currentActive !== lastActiveAccount) {
-        lastActiveAccount = currentActive
-        try {
-          if (currentConfig && typeof currentConfig === 'object') {
-            currentConfig.dynamicModels = []
-            currentConfig.planSyncedAt = 0
-          }
-        } catch {
-          /* ignore read-only or frozen */
-        }
-        overrides.dynamicModels = []
-        overrides.planSyncedAt = 0
-        clearUsageCache()
-        clearProbeCache()
+      const currentIdentity = getCatalogIdentity(liveCfg)
+      if (currentIdentity !== lastCatalogIdentity) {
+        lastCatalogIdentity = currentIdentity
+        resetCatalogSnapshot()
       }
       syncStatsStorage(liveCfg)
     })
@@ -181,7 +197,14 @@ export function apply(ctx, config) {
       if (!svc || (typeof svc.replace !== 'function' && typeof svc.update !== 'function')) {
         throw new Error('DSH settings service is unavailable or non-writable')
       }
+      const prevIdentity = getCatalogIdentity(live())
       const parsed = Config(structuredClone(plainConfig(next)))
+      const nextIdentity = getCatalogIdentity(parsed)
+      const identityChanged = nextIdentity !== prevIdentity
+      if (identityChanged) {
+        if (!('dynamicModels' in next)) parsed.dynamicModels = []
+        if (!('planSyncedAt' in next)) parsed.planSyncedAt = 0
+      }
       const payload = volatileConfig(parsed)
       const rev = getRevision(svc)
       if (typeof svc.replace === 'function') {
@@ -189,6 +212,10 @@ export function apply(ctx, config) {
       } else {
         await svc.update(NS, payload, rev)
       }
+      if (identityChanged) {
+        lastCatalogIdentity = nextIdentity
+        resetCatalogSnapshot()
+      }
       applyConfigMutations(currentConfig, parsed)
       syncStatsStorage(live())
       await syncProviderState(live())
@@ -199,7 +226,14 @@ export function apply(ctx, config) {
       if (!svc || (typeof svc.update !== 'function' && typeof svc.replace !== 'function')) {
         throw new Error('DSH settings service is unavailable or non-writable')
       }
+      const prevIdentity = getCatalogIdentity(live())
       const merged = Config({ ...publicConfig(live()), ...plainConfig(patch) })
+      const nextIdentity = getCatalogIdentity(merged)
+      const identityChanged = nextIdentity !== prevIdentity
+      if (identityChanged) {
+        if (!('dynamicModels' in patch)) merged.dynamicModels = []
+        if (!('planSyncedAt' in patch)) merged.planSyncedAt = 0
+      }
       const payload = volatileConfig(merged)
       const rev = getRevision(svc)
       if (typeof svc.update === 'function') {
@@ -207,6 +241,10 @@ export function apply(ctx, config) {
       } else {
         await svc.replace(NS, payload, rev)
       }
+      if (identityChanged) {
+        lastCatalogIdentity = nextIdentity
+        resetCatalogSnapshot()
+      }
       applyConfigMutations(currentConfig, merged)
       syncStatsStorage(live())
       await syncProviderState(live())
@@ -227,6 +265,21 @@ export function apply(ctx, config) {
     }, 'dsh-clinebot: stats-storage')
   }
 
+  const routeEnv = {
+    live,
+    getSettingsApi: () => settingsApi,
+    syncProviderState,
+    triggerAutoDiscover,
+  }
+
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => {
+      return () => {
+        stopLoopbackProxyServer()
+      }
+    }, 'dsh-clinebot: loopback-proxy-server')
+  }
+
   syncProviderState(live())
   if (typeof ctx.effect === 'function') {
     ctx.effect(() => {
@@ -249,13 +302,6 @@ export function apply(ctx, config) {
       ctx.effect(() => () => unregisterUpdater?.(), 'dsh-clinebot: updater')
     }
 
-    const routeEnv = {
-      live,
-      getSettingsApi: () => settingsApi,
-      syncProviderState,
-      triggerAutoDiscover,
-    }
-
     registerSettingsRoutes(ctx, routeEnv)
     registerAccountsRoutes(ctx, routeEnv)
     registerModelsRoutes(ctx, routeEnv)

package/lib/provider-sync.js

@@ -25,6 +25,7 @@ import { resolveKeyValue } from './credential-refs.js'
 import { resolveAccountPool, getLastRotation } from './account-pool.js'
 import { getLocalProxyToken, LOCAL_PROXY_KEY_ENV } from './proxy-token.js'
 import { saveCredentialKey } from './credential-refs.js'
+import { getProxyPort, detectHostWebServerFence } from './proxy-server.js'
 
 export function resolvePathWithHome(p) {
   let guard = 0
@@ -208,11 +209,29 @@ export async function upsertPiAiProvider(ctx, cfg, activeModelIds) {
 
   const activeAcc = await resolveActiveAccountKey(ctx, cfg)
 
-  const port = ctx?.webServer?.port || process.env.PORT || 3080
-  const isProxy = pub.proxyMode !== false
-  const effectiveBaseUrl = isProxy
-    ? `http://127.0.0.1:${port}/dsh-clinebot/v1`
-    : pub.baseUrl
+  let isProxy = pub.proxyMode !== false
+  let effectiveBaseUrl = pub.baseUrl
+  let proxyPort = getProxyPort()
+
+  if (isProxy) {
+    if (!proxyPort) {
+      proxyPort = ctx?.webServer?.port || process.env.PORT || 3080
+      const isFenced = await detectHostWebServerFence(proxyPort)
+      if (isFenced) {
+        ctx?.logger?.warn?.(
+          `[dsh-clinebot] DesktopWebServer security fence detected on port ${proxyPort} and dedicated loopback proxy is not active. Falling back to direct upstream mode.`
+        )
+        isProxy = false
+      }
+    }
+  }
+
+  if (isProxy && proxyPort) {
+    effectiveBaseUrl = `http://127.0.0.1:${proxyPort}/dsh-clinebot/v1`
+  } else {
+    isProxy = false
+    effectiveBaseUrl = pub.baseUrl
+  }
 
   const localToken = isProxy ? getLocalProxyToken() : undefined
   if (isProxy && localToken) {

package/lib/proxy-server.js

@@ -0,0 +1,145 @@
+/**
+ * Dedicated Loopback Proxy Server (Issues GH #12, #195)
+ *
+ * Runs an isolated loopback HTTP server bound exclusively to 127.0.0.1 (ephemeral port).
+ * Completely bypasses DSH Desktop 2.x DesktopWebServer route fencing (`permits(req)`
+ * requiring `x-dsh-desktop-renderer` header), allowing Node.js host LLM requests to
+ * connect cleanly to loopback proxy endpoints without encountering HTTP 403 "forbidden".
+ */
+
+import http from 'node:http'
+import { createChatCompletionsHandler, createModelsHandler } from './routes/proxy.js'
+
+let activeProxyServer = null
+let activeProxyPort = null
+let startingPromise = null
+
+export function getProxyPort() {
+  return activeProxyPort
+}
+
+export function resetProxyServerState() {
+  if (activeProxyServer) {
+    try {
+      activeProxyServer.close()
+    } catch {
+      /* ignore */
+    }
+  }
+  activeProxyServer = null
+  activeProxyPort = null
+  startingPromise = null
+}
+
+export async function detectHostWebServerFence(port) {
+  if (!port || typeof port !== 'number' || port <= 0) return false
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/dsh-clinebot/v1/models`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(1000),
+    })
+    if (res.status === 403) {
+      const text = await res.text().catch(() => '')
+      if (text.trim().toLowerCase() === 'forbidden') {
+        return true
+      }
+    }
+  } catch {
+    return false
+  }
+  return false
+}
+
+export async function startLoopbackProxyServer(ctx, routeEnv) {
+  if (activeProxyServer && activeProxyPort) {
+    return activeProxyPort
+  }
+  if (startingPromise) {
+    return startingPromise
+  }
+
+  startingPromise = (async () => {
+    try {
+      const chatHandler = createChatCompletionsHandler(ctx, routeEnv)
+      const modelsHandler = createModelsHandler(ctx, routeEnv)
+
+      const server = http.createServer(async (req, res) => {
+        try {
+          const rawUrl = req.url || '/'
+          const path = rawUrl.split('?')[0].replace(/\/+$/, '')
+          if (path === '/dsh-clinebot/v1/chat/completions') {
+            await chatHandler(req, res)
+            return
+          }
+          if (path === '/dsh-clinebot/v1/models') {
+            await modelsHandler(req, res)
+            return
+          }
+          res.statusCode = 404
+          res.setHeader('Content-Type', 'application/json; charset=utf-8')
+          res.end(JSON.stringify({ ok: false, error: 'Not found' }))
+        } catch (err) {
+          if (!res.headersSent) {
+            res.statusCode = 500
+            res.setHeader('Content-Type', 'application/json; charset=utf-8')
+            res.end(JSON.stringify({ ok: false, error: String(err?.message || err) }))
+          }
+        }
+      })
+
+      const port = await new Promise((resolve, reject) => {
+        server.on('error', (err) => {
+          ctx?.logger?.warn?.(`[dsh-clinebot:proxy-server] Server error: ${err?.message || err}`)
+          reject(err)
+        })
+        server.listen(0, '127.0.0.1', () => {
+          const addr = server.address()
+          const assignedPort = typeof addr === 'object' && addr?.port ? addr.port : null
+          if (!assignedPort) {
+            reject(new Error('Failed to obtain assigned ephemeral port'))
+            return
+          }
+          if (typeof server.unref === 'function') {
+            server.unref()
+          }
+          resolve(assignedPort)
+        })
+      })
+
+      activeProxyServer = server
+      activeProxyPort = port
+      ctx?.logger?.info?.(`[dsh-clinebot:proxy-server] Dedicated loopback proxy listening on 127.0.0.1:${port}`)
+      return port
+    } catch (err) {
+      ctx?.logger?.warn?.(`[dsh-clinebot:proxy-server] Failed to bind dedicated loopback proxy server: ${err?.message || err}`)
+      activeProxyServer = null
+      activeProxyPort = null
+      return null
+    } finally {
+      startingPromise = null
+    }
+  })()
+
+  return startingPromise
+}
+
+export async function stopLoopbackProxyServer() {
+  if (!activeProxyServer) return
+  const server = activeProxyServer
+  activeProxyServer = null
+  activeProxyPort = null
+  startingPromise = null
+  return new Promise((resolve) => {
+    server.close(() => {
+      resolve()
+    })
+  })
+}
+
+export async function getOrStartProxyPort(ctx, routeEnv) {
+  if (activeProxyPort) return activeProxyPort
+  if (routeEnv) {
+    return await startLoopbackProxyServer(ctx, routeEnv)
+  }
+  return null
+}

package/lib/routes/proxy.js

@@ -35,13 +35,7 @@ export const USER_AGENT = `@goodandready/dsh-clinebot/${packageVersion}`
 
 export function hasDisallowedBrowserOrigin(req) {
   const secFetchSite = req.headers?.['sec-fetch-site']
-  if (secFetchSite === 'cross-site' || secFetchSite === 'same-site') {
-    return true
-  }
-  if (req.headers?.['origin']) {
-    return true
-  }
-  return false
+  return secFetchSite === 'cross-site' || secFetchSite === 'same-site' || Boolean(req.headers?.['origin'])
 }
 
 export function isAuthorizedProxyRequest(req, accountPool = []) {
@@ -51,26 +45,15 @@ export function isAuthorizedProxyRequest(req, accountPool = []) {
   const token = match[1].trim()
   if (!token) return false
   const localToken = getLocalProxyToken()
-  if (localToken && token === localToken) {
-    return true
-  }
-  if (Array.isArray(accountPool) && accountPool.length > 0) {
-    if (accountPool.some((acc) => acc.value && acc.value === token)) {
-      return true
-    }
-  }
-  return false
+  if (localToken && token === localToken) return true
+  return Array.isArray(accountPool) && accountPool.some((acc) => acc.value && acc.value === token)
 }
 
-export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderState }) {
-  // 1. POST /dsh-clinebot/v1/chat/completions
-  ctx.effect(() => ctx.webServer.register({
-    kind: 'exact',
-    path: '/dsh-clinebot/v1/chat/completions',
-    handler: async (req, res) => {
-      if (req.method !== 'POST') {
-        return writeJson(res, 405, { ok: false, error: 'POST only' })
-      }
+export function createChatCompletionsHandler(ctx, { live, getSettingsApi, syncProviderState }) {
+  return async (req, res) => {
+    if (req.method !== 'POST') {
+      return writeJson(res, 405, { ok: false, error: 'POST only' })
+    }
 
       if (!isLoopbackAddress(req.socket?.remoteAddress)) {
         return writeJson(res, 403, { ok: false, error: 'Loopback access only' })
@@ -102,20 +85,11 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
       const cfg = plainConfig(live())
       const pub = publicConfig(cfg)
 
-      // Session identification
+      const h = req.headers || {}
       const sessionId = String(
-        req.headers['x-dsh-session-id'] ||
-        req.headers['x-session-id'] ||
-        req.headers['session-id'] ||
-        req.headers['session_id'] ||
-        req.headers['x-session-affinity'] ||
-        req.headers['x-client-request-id'] ||
-        body?.session_id ||
-        body?.conversation_id ||
-        body?.prompt_cache_key ||
-        body?.chat_id ||
-        body?.user ||
-        ''
+        h['x-dsh-session-id'] || h['x-session-id'] || h['session-id'] || h['session_id'] ||
+        h['x-session-affinity'] || h['x-client-request-id'] ||
+        body?.session_id || body?.conversation_id || body?.prompt_cache_key || body?.chat_id || body?.user || ''
       ).trim()
 
       if (sessionId) {
@@ -123,15 +97,8 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
         if (!body.conversation_id) body.conversation_id = sessionId
       }
 
-      // Ensure model is set, fallback to defaultModel (#140)
       body.model = String(body.model || pub.defaultModel || DEFAULT_MODEL_ID).trim()
-
-      // Inject model reasoning effort if model has default configured and payload omitted it
-      if (
-        pub.modelReasoningDefaults &&
-        pub.modelReasoningDefaults[body.model] &&
-        !body.reasoning_effort
-      ) {
+      if (pub.modelReasoningDefaults?.[body.model] && !body.reasoning_effort) {
         body.reasoning_effort = pub.modelReasoningDefaults[body.model]
       }
 
@@ -532,51 +499,67 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           details: lastError?.message || null
         }
       })
-    },
+    }
+  }
+
+export function createModelsHandler(ctx, { live }) {
+  return async (req, res) => {
+    if (req.method !== 'GET') {
+      return writeJson(res, 405, { ok: false, error: 'GET only' })
+    }
+
+    if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+      return writeJson(res, 403, { ok: false, error: 'Loopback access only' })
+    }
+
+    if (hasDisallowedBrowserOrigin(req)) {
+      return writeJson(res, 403, { ok: false, error: 'Cross-site or browser requests to proxy are forbidden' })
+    }
+
+    const pool = await resolveAccountPool(ctx, live())
+    if (!isAuthorizedProxyRequest(req, pool)) {
+      return writeJson(res, 401, { ok: false, error: 'Unauthorized: missing or invalid bearer token' })
+    }
+
+    const pub = publicConfig(live())
+    const dynamic = Array.isArray(pub.dynamicModels) ? pub.dynamicModels : []
+    const custom = Array.isArray(pub.customModels) ? pub.customModels : []
+    const overrides = Array.isArray(pub.modelContextOverrides) ? pub.modelContextOverrides : []
+    const allModels = getAllModels(dynamic, overrides, custom)
+
+    const modelsData = allModels.map(m => ({
+      id: m.id,
+      object: 'model',
+      created: 1700000000,
+      owned_by: 'clinebot',
+      permission: [],
+      root: m.id,
+      parent: null
+    }))
+
+    writeJson(res, 200, {
+      object: 'list',
+      data: modelsData
+    })
+  }
+}
+
+export function registerProxyRoutes(ctx, routeEnv) {
+  const chatHandler = createChatCompletionsHandler(ctx, routeEnv)
+  const modelsHandler = createModelsHandler(ctx, routeEnv)
+
+  // 1. POST /dsh-clinebot/v1/chat/completions
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-clinebot/v1/chat/completions',
+    handler: chatHandler,
   }), 'dsh-clinebot: /v1/chat/completions')
 
   // 2. GET /dsh-clinebot/v1/models (OpenAI standard)
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-clinebot/v1/models',
-    handler: async (req, res) => {
-      if (req.method !== 'GET') {
-        return writeJson(res, 405, { ok: false, error: 'GET only' })
-      }
-
-      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
-        return writeJson(res, 403, { ok: false, error: 'Loopback access only' })
-      }
-
-      if (hasDisallowedBrowserOrigin(req)) {
-        return writeJson(res, 403, { ok: false, error: 'Cross-site or browser requests to proxy are forbidden' })
-      }
-
-      const pool = await resolveAccountPool(ctx, live())
-      if (!isAuthorizedProxyRequest(req, pool)) {
-        return writeJson(res, 401, { ok: false, error: 'Unauthorized: missing or invalid bearer token' })
-      }
-
-      const pub = publicConfig(live())
-      const dynamic = Array.isArray(pub.dynamicModels) ? pub.dynamicModels : []
-      const custom = Array.isArray(pub.customModels) ? pub.customModels : []
-      const overrides = Array.isArray(pub.modelContextOverrides) ? pub.modelContextOverrides : []
-      const allModels = getAllModels(dynamic, overrides, custom)
-
-      const modelsData = allModels.map(m => ({
-        id: m.id,
-        object: 'model',
-        created: 1700000000,
-        owned_by: 'clinebot',
-        permission: [],
-        root: m.id,
-        parent: null
-      }))
-
-      writeJson(res, 200, {
-        object: 'list',
-        data: modelsData
-      })
-    },
+    handler: modelsHandler,
   }), 'dsh-clinebot: /v1/models')
 }
+

package/lib/routes/settings.js

@@ -93,7 +93,10 @@ export function registerSettingsRoutes(ctx, { live, getSettingsApi, syncProvider
         const base = plainConfig(live()) || {}
         delete base.enabledModels
         const merged = { ...base, ...rawPayload }
-        if (rawPayload.activeAccount !== undefined && String(rawPayload.activeAccount).trim() !== String(base.activeAccount || "").trim()) {
+        const activeChanged = rawPayload.activeAccount !== undefined && String(rawPayload.activeAccount).trim() !== String(base.activeAccount || "").trim()
+        const apiKeyEnvChanged = rawPayload.apiKeyEnv !== undefined && String(rawPayload.apiKeyEnv).trim() !== String(base.apiKeyEnv || "").trim()
+        const baseUrlChanged = rawPayload.baseUrl !== undefined && String(rawPayload.baseUrl).trim().replace(/\/+$/, '') !== String(base.baseUrl || "").trim().replace(/\/+$/, '')
+        if (activeChanged || apiKeyEnvChanged || baseUrlChanged) {
           if (!("dynamicModels" in rawPayload)) merged.dynamicModels = []
           if (!("planSyncedAt" in rawPayload)) merged.planSyncedAt = 0
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.5.13",
+  "version": "0.5.16",
   "description": "DeepSeek Harness companion for ClineBot / ClinePass: dynamic subscription models sync, quota exhaustion warnings, session metrics, dedicated settings page, live usage limits, and /cline slash-command.",
   "license": "MIT",
   "type": "module",