@goodandready/dsh-clinebot 0.5.6 → 0.5.7

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.7] - 2026-09-30
+
+### Fixed
+- **Active Account Pinning & Account Identity Unification (Issue #161)**: Resolved issue where proxy router ignored manually pinned active account and routed requests to secondary keys. Unified account identification across `id`, `apiKeyEnv`, and `label` in session routing, round-robin fallback, and cooldown tracking.
+- **Account Pool Quota Metadata Enrichment (Issue #162)**: Provided real-time quota window utilization metadata (`remainingPercent`, `percentUsed`, `resetsAt`) to least-used account routing strategy. Handled unknown/unprobed quotas safely to prevent routing bias towards exhausted accounts.
+- **Pi-AI Provider Session Affinity Header Propagation (Issue #163)**: Enabled `sendSessionAffinityHeaders: true` and `sessionAffinityFormat: 'openrouter'` in `@earendil-works/pi-ai` provider and model compatibility options. Expanded proxy session identification to extract session IDs from `x-session-id`, `x-dsh-session-id`, `session-id`, `x-session-affinity`, and client body parameters, preserving conversation affinity.
+- **Client SSE Disconnection Upstream Abort (Issue #164)**: Monitored client response `close` events during streaming. Aborts upstream fetch and cancels ReadableStream reader immediately when a client disconnects prematurely, avoiding resource waste and orphaned upstream requests. Guarded writes and cleaned up listeners reliably.
+- **Decoupled Connect Timeout & Streaming Idle Watchdog (Issue #165)**: Separated initial HTTP connect / header timeout (`connectTimeoutMs`, default 15s) from active streaming idle timeout (`streamIdleTimeoutMs`, default 30s). Prevented healthy long SSE streams from being cut off by monolithic timeouts. Added rearmable idle watchdog that signals client errors on stalls and accurately accounts failed streams with `isError: true` in token analytics instead of false successes.
+
 ## [0.5.6] - 2026-09-30
 
 ### Security

package/lib/account-pool.js

@@ -32,6 +32,40 @@ function toPlainSnapshot(cfg) {
   return out
 }
 
+export function getAccountQuotaSnapshot(accValue) {
+  if (!accValue || typeof accValue !== 'string') return null
+  const cacheKey = `cline:usage:${accValue.slice(-8)}`
+  const cached = usageCache.get(cacheKey)?.data
+  if (!cached?.windows) return null
+
+  const now = Date.now()
+  const evaluateWindow = (w) => {
+    if (!w || typeof w.percentUsed !== 'number') return null
+    if (w.resetsAt) {
+      const resetTime = new Date(w.resetsAt).getTime()
+      if (!Number.isNaN(resetTime) && now >= resetTime) {
+        return 0
+      }
+    }
+    return w.percentUsed
+  }
+
+  const fh = evaluateWindow(cached.windows.fiveHour)
+  const wk = evaluateWindow(cached.windows.weekly)
+  const mo = evaluateWindow(cached.windows.monthly)
+
+  const activePcts = [fh, wk, mo].filter((p) => typeof p === 'number')
+  const percentUsed = activePcts.length > 0 ? Math.max(...activePcts) : null
+
+  return {
+    percentUsed,
+    fiveHour: fh,
+    weekly: wk,
+    monthly: mo,
+    raw: cached,
+  }
+}
+
 export async function resolveAccountPool(ctx, cfg) {
   const apiKeyEnv = textSetting(cfg?.apiKeyEnv) || DEFAULT_API_KEY_ENV
   const defaultSlot = {
@@ -48,14 +82,21 @@ export async function resolveAccountPool(ctx, cfg) {
     const slot = allSlots[i]
     const envName = textSetting(slot.apiKeyEnv) || (i === 0 ? apiKeyEnv : `CLINEBOT_API_KEY_${i + 1}`)
     const keyInfo = await resolveKeyValue(ctx, envName)
+    const slotId = slot.id || (i === 0 ? 'default' : `account-${i + 1}`)
+    const isPinned = activeAccount === 'auto'
+      ? false
+      : (activeAccount ? (activeAccount === envName || activeAccount === slotId) : i === 0)
+    const quota = keyInfo.value ? getAccountQuotaSnapshot(keyInfo.value) : null
     resolved.push({
-      id: slot.id || (i === 0 ? 'default' : `account-${i + 1}`),
+      id: slotId,
       label: textSetting(slot.label) || (i === 0 ? 'Default' : `Account ${i + 1}`),
       apiKeyEnv: envName,
       present: Boolean(keyInfo.value),
       source: keyInfo.source,
       value: keyInfo.value,
-      isPinned: activeAccount ? activeAccount === envName : i === 0,
+      isPinned,
+      percentUsed: typeof quota?.percentUsed === 'number' ? quota.percentUsed : null,
+      quota,
     })
   }
 

package/lib/cline-client.js

@@ -26,6 +26,7 @@ export const DEFAULT_BASE_URL = 'https://api.cline.bot/api/v1'
 export const DEFAULT_API_KEY_ENV = 'CLINEBOT_API_KEY'
 export const DEFAULT_TIMEOUT_MS = 15000
 export const DEFAULT_SMOKE_TIMEOUT_MS = 25000
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 30000
 const USAGE_CACHE_TTL_MS = 60000
 
 export { PROVIDER_ID, PROVIDER_DISPLAY_NAME, DEFAULT_MODEL_ID }
@@ -486,13 +487,18 @@ export function buildPiAiProvider({
         if (validEfforts.includes(key)) efforts[key] = key === 'off' ? (v === undefined ? null : v) : (typeof v === 'string' && v.trim() ? v.trim() : key)
       }
     }
+    const modelCompat = {
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+    }
     if (efforts && Object.keys(efforts).length) {
       if (!('off' in efforts)) efforts.off = null
       res.reasoningEfforts = efforts
-      res.compat = { supportsReasoningEffort: true }
+      modelCompat.supportsReasoningEffort = true
     } else {
       res.reasoningEfforts = false
     }
+    res.compat = modelCompat
     return res
   })
 
@@ -502,7 +508,11 @@ export function buildPiAiProvider({
     baseURL: normalizeBaseUrl(baseUrl),
     apiKeyEnv: apiKeyEnv || DEFAULT_API_KEY_ENV,
     ...(apiKey ? { apiKey } : {}),
-    compat: { supportsReasoningEffort: true },
+    compat: {
+      supportsReasoningEffort: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+    },
     models: modelList,
   }
 }

package/lib/config.js

@@ -4,6 +4,7 @@ import {
   DEFAULT_API_KEY_ENV,
   DEFAULT_TIMEOUT_MS,
   DEFAULT_SMOKE_TIMEOUT_MS,
+  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   normalizeBaseUrl,
 } from './cline-client.js'
 import {
@@ -76,6 +77,8 @@ export const Config = z.object({
     .description('HTTP probe timeout in milliseconds.').volatile(),
   smokeTimeoutMs: z.number().default(DEFAULT_SMOKE_TIMEOUT_MS)
     .description('Timeout for smoke chat completions in milliseconds.').volatile(),
+  streamIdleTimeoutMs: z.number().default(DEFAULT_STREAM_IDLE_TIMEOUT_MS)
+    .description('Idle timeout between SSE stream chunks in milliseconds.').volatile(),
   modelsCachePath: z.string().default('~/.dsh/clinebot-models-cache.json')
     .description('Local on-disk cache path for models snapshot.').volatile(),
   accounts: z.array(z.object({
@@ -170,6 +173,7 @@ export function publicConfig(cfg) {
     enabledModels: activeIds,
     timeoutMs: Number(cfg?.timeoutMs) || DEFAULT_TIMEOUT_MS,
     smokeTimeoutMs: Number(cfg?.smokeTimeoutMs) || DEFAULT_SMOKE_TIMEOUT_MS,
+    streamIdleTimeoutMs: Number(cfg?.streamIdleTimeoutMs) || DEFAULT_STREAM_IDLE_TIMEOUT_MS,
     modelsCachePath: String(cfg?.modelsCachePath || '~/.dsh/clinebot-models-cache.json'),
     accounts: Array.isArray(cfg?.accounts) ? cfg.accounts : [],
     activeAccount: String(cfg?.activeAccount || ''),

package/lib/provider-sync.js

@@ -161,9 +161,6 @@ export async function buildStatus(ctx, cfg) {
       source: activeAcc.source || key.source,
     },
     accounts: pool.map((acc) => {
-      const cacheKey = `cline:usage:${(acc.value || '').slice(-8)}`
-      const cached = usageCache.get(cacheKey)?.data
-      const pct = cached?.windows?.weekly?.percentUsed ?? cached?.windows?.monthly?.percentUsed ?? cached?.windows?.fiveHour?.percentUsed ?? null
       return {
         id: acc.id,
         label: acc.label,
@@ -171,7 +168,7 @@ export async function buildStatus(ctx, cfg) {
         present: acc.present,
         source: acc.source,
         isPinned: acc.isPinned,
-        percentUsed: typeof pct === 'number' ? pct : null,
+        percentUsed: typeof acc.percentUsed === 'number' ? acc.percentUsed : null,
       }
     }),
     activeAccount: activeAcc.apiKeyEnv,

package/lib/routes/proxy.js

@@ -106,6 +106,11 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
       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?.chat_id ||
         body?.user ||
@@ -127,6 +132,24 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
       const isStreaming = Boolean(body.stream)
       const configuredAccounts = pool.filter(a => a.present && a.value)
 
+      const clientAbortCtrl = new AbortController()
+      let clientClosed = false
+      const onClientClose = () => {
+        clientClosed = true
+        if (!res.writableFinished) {
+          clientAbortCtrl.abort()
+        }
+      }
+      if (typeof res.on === 'function') res.on('close', onClientClose)
+      if (typeof req.on === 'function') req.on('close', onClientClose)
+
+      const cleanupClientListeners = () => {
+        if (typeof res.off === 'function') res.off('close', onClientClose)
+        else if (typeof res.removeListener === 'function') res.removeListener('close', onClientClose)
+        if (typeof req.off === 'function') req.off('close', onClientClose)
+        else if (typeof req.removeListener === 'function') req.removeListener('close', onClientClose)
+      }
+
       const maxRetries = Math.max(1, configuredAccounts.length)
       let attempt = 0
       let lastError = null
@@ -135,10 +158,16 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
       while (attempt < maxRetries) {
         attempt += 1
 
+        if (clientAbortCtrl.signal.aborted || clientClosed) {
+          cleanupClientListeners()
+          return
+        }
+
         const routeResult = resolveSessionAccount(sessionId, pool, pub.activeAccount)
         const targetAccount = routeResult.account
 
         if (!targetAccount || !targetAccount.value) {
+          cleanupClientListeners()
           return writeJson(res, 503, {
             error: {
               message: 'No available ClinePass API keys configured in pool',
@@ -156,16 +185,17 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           'User-Agent': USER_AGENT
         }
 
-        const upstreamTimeoutMs = Math.max(1000, Number(pub.timeoutMs) || 60000)
-        const timeoutSignal = AbortSignal.timeout(upstreamTimeoutMs)
-        const clientAbortCtrl = new AbortController()
-        const onReqClose = () => {
-          clientAbortCtrl.abort()
-        }
-        if (typeof req.on === 'function') {
-          req.on('close', onReqClose)
-        }
-        const fetchSignal = AbortSignal.any([clientAbortCtrl.signal, timeoutSignal])
+        const connectTimeoutMs = Math.max(50, Number(pub.connectTimeoutMs || pub.timeoutMs) || 15000)
+        const streamIdleTimeoutMs = Math.max(50, Number(pub.streamIdleTimeoutMs || pub.idleTimeoutMs) || 30000)
+
+        const connectAbortCtrl = new AbortController()
+        let connectTimedOut = false
+        const connectTimer = setTimeout(() => {
+          connectTimedOut = true
+          connectAbortCtrl.abort(new Error(`Upstream connect timeout after ${connectTimeoutMs}ms`))
+        }, connectTimeoutMs)
+
+        const fetchSignal = AbortSignal.any([clientAbortCtrl.signal, connectAbortCtrl.signal])
 
         let upstreamRes
         try {
@@ -177,25 +207,29 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
             keepalive: true
           })
         } catch (fetchErr) {
-          if (clientAbortCtrl.signal.aborted) {
-            // Client closed connection, stop processing
+          clearTimeout(connectTimer)
+          if (clientAbortCtrl.signal.aborted || clientClosed) {
+            cleanupClientListeners()
             return
           }
           lastError = fetchErr
-          const isTimeout = timeoutSignal.aborted || fetchErr.name === 'TimeoutError' || String(fetchErr).includes('timeout')
+          const isTimeout = connectTimedOut || connectAbortCtrl.signal.aborted || fetchErr.name === 'TimeoutError' || String(fetchErr).includes('timeout')
           if (isTimeout) {
             hadTimeout = true
-            const accountId = targetAccount.id || targetAccount.label
+            const accountId = targetAccount.apiKeyEnv || targetAccount.id || targetAccount.label
             markAccountCooldown(accountId, 60000, null, 'upstream_timeout')
-            ctx?.logger?.warn?.(`[dsh-clinebot:proxy] Account "${accountId}" upstream timed out after ${upstreamTimeoutMs}ms, attempting failover (attempt ${attempt}/${maxRetries})`)
+            if (targetAccount.id && targetAccount.id !== accountId) markAccountCooldown(targetAccount.id, 60000, null, 'upstream_timeout')
+            ctx?.logger?.warn?.(`[dsh-clinebot:proxy] Account "${accountId}" upstream connect timed out after ${connectTimeoutMs}ms, attempting failover (attempt ${attempt}/${maxRetries})`)
           }
           continue
         }
+        clearTimeout(connectTimer)
 
         // If upstream rejected with 429 or 402 quota exhaustion before streaming, failover!
         if (upstreamRes.status === 429 || upstreamRes.status === 402) {
-          const accountId = targetAccount.id || targetAccount.label
+          const accountId = targetAccount.apiKeyEnv || targetAccount.id || targetAccount.label
           markAccountCooldown(accountId, 60000, null, 'upstream_429')
+          if (targetAccount.id && targetAccount.id !== accountId) markAccountCooldown(targetAccount.id, 60000, null, 'upstream_429')
           recordUsage({
             model: body.model,
             accountId,
@@ -221,6 +255,8 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           let completionTokens = 0
           let totalTokens = 0
           let buffer = ''
+          let streamError = null
+          let streamCompletedCleanly = false
 
           const reader = upstreamRes.body.getReader()
           const decoder = new TextDecoder('utf8')
@@ -229,22 +265,67 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           const onStreamAbort = () => {
             streamAborted = true
             try {
-              reader.cancel().catch(() => {})
-            } catch {
-              /* ignore */
+              reader.cancel('client closed response').catch(() => {})
+            } catch { /* reader already cancelled or closed */ }
+          }
+
+          if (clientAbortCtrl.signal.aborted || clientClosed) {
+            onStreamAbort()
+          } else {
+            clientAbortCtrl.signal.addEventListener('abort', onStreamAbort, { once: true })
+          }
+
+          let idleTimer = null
+          let idleTimedOut = false
+          const resetIdleTimer = () => {
+            if (idleTimer) clearTimeout(idleTimer)
+            idleTimer = setTimeout(() => {
+              idleTimedOut = true
+              streamError = new Error(`Stream idle timeout after ${streamIdleTimeoutMs}ms`)
+              try {
+                reader.cancel('stream idle timeout').catch(() => {})
+              } catch { /* reader already cancelled or closed */ }
+            }, streamIdleTimeoutMs)
+          }
+
+          const clearIdleTimer = () => {
+            if (idleTimer) {
+              clearTimeout(idleTimer)
+              idleTimer = null
             }
           }
-          if (typeof req.on === 'function') {
-            req.on('close', onStreamAbort)
+
+          let totalTimer = null
+          if (pub.streamTotalTimeoutMs && Number(pub.streamTotalTimeoutMs) > 0) {
+            const totalMs = Number(pub.streamTotalTimeoutMs)
+            totalTimer = setTimeout(() => {
+              streamError = new Error(`Stream total timeout after ${totalMs}ms`)
+              try {
+                reader.cancel('stream total timeout').catch(() => {})
+              } catch { /* reader already cancelled or closed */ }
+            }, totalMs)
           }
 
           try {
+            resetIdleTimer()
             while (true) {
+              if (streamAborted || clientAbortCtrl.signal.aborted || clientClosed) break
               const { done, value } = await reader.read()
-              if (done || streamAborted) break
+              if (idleTimedOut || streamError) break
+              if (done || streamAborted) {
+                if (done && !streamAborted && !clientClosed && !idleTimedOut && !streamError) {
+                  streamCompletedCleanly = true
+                }
+                break
+              }
+
+              resetIdleTimer()
 
               const chunkStr = decoder.decode(value, { stream: true })
-              res.write(value)
+              if (!res.destroyed && !res.writableEnded) {
+                res.write(value)
+              }
+              if (streamAborted || clientAbortCtrl.signal.aborted || clientClosed) break
 
               // Parse SSE lines for usage metrics
               buffer += chunkStr
@@ -268,14 +349,34 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
               }
             }
           } catch (streamErr) {
+            streamError = streamErr
             ctx?.logger?.warn?.('[dsh-clinebot:proxy] Stream read error: ' + (streamErr?.message || streamErr))
           } finally {
+            clearIdleTimer()
+            if (totalTimer) clearTimeout(totalTimer)
+            clientAbortCtrl.signal.removeEventListener('abort', onStreamAbort)
+            cleanupClientListeners()
             try {
               reader.releaseLock()
-            } catch (err) {
-              /* ignore lock release error if reader already closed */
+            } catch (err) { /* ignore lock release error if reader closed */ }
+
+            const isStreamFailed = Boolean(streamError || idleTimedOut || clientClosed || clientAbortCtrl.signal.aborted || !streamCompletedCleanly)
+
+            if (!res.destroyed && !res.writableEnded) {
+              if (isStreamFailed && (idleTimedOut || streamError)) {
+                try {
+                  const errPayload = JSON.stringify({
+                    error: {
+                      message: streamError?.message || 'Stream interrupted or timed out',
+                      type: 'stream_error',
+                      code: idleTimedOut ? 'stream_idle_timeout' : 'stream_error'
+                    }
+                  })
+                  res.write(`data: ${errPayload}\n\n`)
+                } catch { /* reader already cancelled or closed */ }
+              }
+              res.end()
             }
-            res.end()
 
             recordUsage({
               model: body.model,
@@ -283,6 +384,7 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
               promptTokens,
               completionTokens,
               totalTokens: totalTokens || (promptTokens + completionTokens),
+              isError: isStreamFailed,
               statsPath: pub.statsPath
             })
           }
@@ -298,17 +400,16 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           resJson = null
         }
 
-        if (resJson?.usage) {
-          recordUsage({
-            model: body.model,
-            accountId: targetAccount.id || targetAccount.label,
-            promptTokens: resJson.usage.prompt_tokens,
-            completionTokens: resJson.usage.completion_tokens,
-            totalTokens: resJson.usage.total_tokens,
-            isError: upstreamRes.status >= 400,
-            statsPath: pub.statsPath
-          })
-        }
+        cleanupClientListeners()
+        recordUsage({
+          model: body.model,
+          accountId: targetAccount.id || targetAccount.label,
+          promptTokens: resJson?.usage?.prompt_tokens || 0,
+          completionTokens: resJson?.usage?.completion_tokens || 0,
+          totalTokens: resJson?.usage?.total_tokens || 0,
+          isError: upstreamRes.status >= 400,
+          statsPath: pub.statsPath
+        })
 
         res.statusCode = upstreamRes.status
         res.setHeader('Content-Type', 'application/json; charset=utf-8')
@@ -316,6 +417,7 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
         return
       }
 
+      cleanupClientListeners()
       // Exhausted all retries
       if (hadTimeout) {
         return writeJson(res, 504, {

package/lib/session-router.js

@@ -101,6 +101,20 @@ export function clearAccountCooldown(accountId) {
   }
 }
 
+export function matchesAccount(acc, identifier) {
+  if (!acc || !identifier) return false
+  return acc.id === identifier || acc.apiKeyEnv === identifier || acc.label === identifier
+}
+
+export function isAccountBlocked(acc) {
+  if (!acc) return false
+  return Boolean(
+    (acc.id && isAccountInCooldown(acc.id)) ||
+    (acc.apiKeyEnv && isAccountInCooldown(acc.apiKeyEnv)) ||
+    (acc.label && isAccountInCooldown(acc.label))
+  )
+}
+
 /**
  * Select the best account from the pool based on least-used quota.
  * Lowest percentUsed is prioritized.
@@ -108,6 +122,14 @@ export function clearAccountCooldown(accountId) {
  * @param {Array<Object>} accounts Pool of accounts
  * @returns {Object|null} Selected account or null
  */
+export function getAccountUsageMetric(acc) {
+  if (typeof acc?.percentUsed === 'number') {
+    return acc.percentUsed
+  }
+  // Unknown quota is treated as 50% neutral midpoint rather than assuming 0% completely free
+  return 50
+}
+
 export function selectLeastUsedAccount(accounts = []) {
   if (!Array.isArray(accounts) || accounts.length === 0) {
     return null
@@ -116,7 +138,7 @@ export function selectLeastUsedAccount(accounts = []) {
   // Filter available accounts that have keys present and are not in cooldown
   const available = accounts.filter(acc => {
     if (!acc || acc.present === false) return false
-    return !isAccountInCooldown(acc.id || acc.label)
+    return !isAccountBlocked(acc)
   })
 
   const candidatePool = available.length > 0 ? available : accounts.filter(a => a && a.present !== false)
@@ -124,10 +146,10 @@ export function selectLeastUsedAccount(accounts = []) {
     return accounts[0] || null
   }
 
-  // Sort by lowest percentUsed (least used). If percentUsed is null/undefined, treat as 0% used
+  // Sort by lowest percentUsed (least used). Unknown quota is treated as neutral 50%
   const sorted = [...candidatePool].sort((a, b) => {
-    const aUsed = typeof a.percentUsed === 'number' ? a.percentUsed : 0
-    const bUsed = typeof b.percentUsed === 'number' ? b.percentUsed : 0
+    const aUsed = getAccountUsageMetric(a)
+    const bUsed = getAccountUsageMetric(b)
     return aUsed - bUsed
   })
 
@@ -139,50 +161,85 @@ export function selectLeastUsedAccount(accounts = []) {
  *
  * @param {string|null} sessionId Unique session or conversation identifier
  * @param {Array<Object>} accounts Configured accounts pool
- * @param {string} [defaultActiveId] Fallback active account ID
+ * @param {string} [defaultActiveId] Explicit active account ID, envName or 'auto'
  * @returns {{ account: Object|null, isReassigned: boolean, reason: string }}
  */
 export function resolveSessionAccount(sessionId, accounts = [], defaultActiveId = '') {
-  const safeAccounts = Array.isArray(accounts) ? accounts : []
+  const safeAccounts = Array.isArray(accounts) ? accounts.filter(a => a && a.present !== false) : []
   if (safeAccounts.length === 0) {
-    return { account: null, isReassigned: false, reason: 'empty_pool' }
+    const fallback = Array.isArray(accounts) && accounts.length > 0 ? accounts[0] : null
+    return { account: fallback, isReassigned: false, reason: 'empty_pool' }
   }
 
-  // If no sessionId is provided, use least-used account or default active
+  // Determine explicit pin / active account policy
+  const isAutoMode = defaultActiveId === 'auto'
+  let pinnedAccount = null
+  if (!isAutoMode) {
+    if (defaultActiveId) {
+      pinnedAccount = safeAccounts.find(a => matchesAccount(a, defaultActiveId)) || null
+    }
+    if (!pinnedAccount) {
+      pinnedAccount = safeAccounts.find(a => a.isPinned) || null
+    }
+  }
+
+  const pinnedAvailable = pinnedAccount && !isAccountBlocked(pinnedAccount) ? pinnedAccount : null
+
+  // If no sessionId provided:
   if (!sessionId) {
-    const best = selectLeastUsedAccount(safeAccounts) || safeAccounts.find(a => a.id === defaultActiveId) || safeAccounts[0]
-    return { account: best, isReassigned: false, reason: 'no_session_id' }
+    if (pinnedAvailable) {
+      return { account: pinnedAvailable, isReassigned: false, reason: 'pinned_active' }
+    }
+    const best = selectLeastUsedAccount(safeAccounts) || safeAccounts[0]
+    return { account: best, isReassigned: false, reason: pinnedAccount ? 'pinned_in_cooldown_fallback' : 'no_session_id' }
   }
 
-  let existing = sessions.get(sessionId)
   const now = Date.now()
+  let existing = sessions.get(sessionId)
+
   if (existing) {
-    // TTL eviction check
+    // Check TTL
     if (now - existing.lastUsedAt > SESSION_TTL_MS) {
       sessions.delete(sessionId)
       existing = null
-    } else {
-      const assigned = safeAccounts.find(a => (a.id || a.label) === existing.accountId)
-      // If assigned account is still valid and NOT in cooldown, keep sticky pin
-      if (assigned && !isAccountInCooldown(assigned.id || assigned.label)) {
-        existing.lastUsedAt = now
-        return { account: assigned, isReassigned: false, reason: 'sticky_pinned' }
-      }
-      // Failover: account was deleted or entered cooldown mid-session
     }
   }
 
-  // Prune before adding a brand new session if capacity reached
+  // If manual pin is configured and available:
+  if (pinnedAvailable) {
+    const reassigned = Boolean(existing && !matchesAccount(pinnedAvailable, existing.accountId))
+    sessions.set(sessionId, {
+      accountId: pinnedAvailable.apiKeyEnv || pinnedAvailable.id,
+      assignedAt: existing ? existing.assignedAt : now,
+      lastUsedAt: now
+    })
+    return {
+      account: pinnedAvailable,
+      isReassigned: reassigned,
+      reason: reassigned ? 'pinned_override' : (existing ? 'sticky_pinned' : 'pinned_active')
+    }
+  }
+
+  // If in auto mode or pinned account is unavailable:
+  if (existing) {
+    const assigned = safeAccounts.find(a => matchesAccount(a, existing.accountId))
+    if (assigned && !isAccountBlocked(assigned)) {
+      existing.lastUsedAt = now
+      return { account: assigned, isReassigned: false, reason: 'sticky_pinned' }
+    }
+    // Otherwise, failover is needed
+  }
+
+  // Prune if needed
   if (!existing && sessions.size >= MAX_SESSIONS) {
     pruneSessions(now, MAX_SESSIONS - 1, SESSION_TTL_MS)
   }
 
-  // New session or mid-session failover: pick least-used account
-  const chosen = selectLeastUsedAccount(safeAccounts) || safeAccounts.find(a => a.id === defaultActiveId) || safeAccounts[0]
+  // Pick least-used available account
+  const chosen = selectLeastUsedAccount(safeAccounts) || safeAccounts[0]
   if (chosen) {
-    const chosenId = chosen.id || chosen.label
     sessions.set(sessionId, {
-      accountId: chosenId,
+      accountId: chosen.apiKeyEnv || chosen.id,
       assignedAt: existing ? existing.assignedAt : now,
       lastUsedAt: now
     })
@@ -191,7 +248,7 @@ export function resolveSessionAccount(sessionId, accounts = [], defaultActiveId
   return {
     account: chosen,
     isReassigned: Boolean(existing),
-    reason: existing ? 'mid_session_failover' : 'new_session_assigned'
+    reason: existing ? 'mid_session_failover' : (pinnedAccount ? 'pinned_in_cooldown_fallback' : 'new_session_assigned')
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "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",