@goodandready/dsh-clinebot 0.5.0 → 0.5.2

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.2] - 2026-09-28
+
+### Security
+- **Proxy Endpoints Local Bearer Auth & CSRF Protection (Issue #145)**: Secured OpenAI-compatible proxy routes (`/dsh-clinebot/v1/chat/completions` and `/dsh-clinebot/v1/models`) by generating a unique local proxy token (`CLINEBOT_LOCAL_PROXY_TOKEN`) passed as `apiKey` to the DSH provider. Requests missing or with invalid Bearer tokens receive HTTP 401 Unauthorized. Incoming browser requests containing `Origin` or `Sec-Fetch-Site: cross-site|same-site` are rejected with HTTP 403 Forbidden to protect against LAN abuse and cross-site request forgery.
+
+### Added & Improved
+- **Test Suite Isolation Sandbox (Issue #146)**: Introduced `test/_setup.mjs` configuring a dedicated temporary filesystem sandbox for `HOME` and `DSH_HOME` during automated test runs. Updated `lib/stats-storage.js` and `lib/provider-sync.js` to respect `DSH_HOME`. Added protective test verifying real `~/.dsh` files are untouched.
+- **Dynamic Proxy User-Agent & Upstream Timeout Failover (Issue #147)**: User-Agent in proxy upstream requests now dynamically reflects the exact package version from `package.json`. Upstream completions use an abort timeout (`AbortSignal.any`); upon timing out, the request automatically rotates to the next available account in the pool, returning HTTP 504 Gateway Timeout if all accounts fail.
+- **Self-Updater Concurrency Lock & Argument Cleanup (Issue #148)**: Removed deprecated `--config.minimumReleaseAge=0` flag from `dsh plugin add` invocations. Added `package.json.lock` verification inspecting PID liveness: active installations return HTTP 409 Conflict with PID, while stale locks from terminated processes are cleaned up automatically.
+
+## [0.5.1] - 2026-09-28
+
+### Fixed
+- **Host Process Crash on Stats Save (Issue #141, GitHub #9)**: Safely unwrap volatile Schemastery `{ get }` references, getter functions, and non-string inputs in `resolvePath`. Wrapped `saveStatsSync` in `try/catch` inside `queueSaveStats` timer callback to guarantee disk persistence failures never become uncaught exceptions terminating the DSH host process. Updated `lib/index.js` to pass `publicConfig(live()).statsPath`.
+- **Large Context / Multimodal Proxy Rejection (Issue #142, GitHub #10)**: Increased request body reading limit on `/dsh-clinebot/v1/chat/completions` from 256 KB to 64 MB, preventing HTTP 400 `"body too large"` errors on long conversational sessions and multimodal requests.
+- **Model Cache Path Resolution (Issue #143)**: Added safe volatile reference and getter unwrapping to `resolvePathWithHome` in `lib/provider-sync.js`, preventing `TypeError [ERR_INVALID_ARG_TYPE]` on disk cache operations.
+
 ## [0.5.0] - 2026-09-27
 
 ### Security

package/lib/cline-client.js

@@ -448,6 +448,7 @@ export async function smokeChat(baseUrl, apiKey, {
 export function buildPiAiProvider({
   baseUrl = DEFAULT_BASE_URL,
   apiKeyEnv = DEFAULT_API_KEY_ENV,
+  apiKey,
   models = [],
   customModels = [],
   displayName = PROVIDER_DISPLAY_NAME,
@@ -500,6 +501,7 @@ export function buildPiAiProvider({
     api: 'openai-completions',
     baseURL: normalizeBaseUrl(baseUrl),
     apiKeyEnv: apiKeyEnv || DEFAULT_API_KEY_ENV,
+    ...(apiKey ? { apiKey } : {}),
     compat: { supportsReasoningEffort: true },
     models: modelList,
   }

package/lib/index.js

@@ -210,7 +210,7 @@ export function apply(ctx, config) {
                   totalTokens: promptTokens + completionTokens,
                   isError: true,
                   is429,
-                  statsPath: live().statsPath,
+                  statsPath: publicConfig(live()).statsPath,
                 })
                 if (is429 || isExceeded) {
                   handleStream429()
@@ -237,7 +237,7 @@ export function apply(ctx, config) {
                   promptTokens,
                   completionTokens,
                   totalTokens: promptTokens + completionTokens,
-                  statsPath: live().statsPath,
+                  statsPath: publicConfig(live()).statsPath,
                 })
               }
             }
@@ -256,7 +256,7 @@ export function apply(ctx, config) {
               promptTokens,
               completionTokens,
               totalTokens: promptTokens + completionTokens,
-              statsPath: live().statsPath,
+              statsPath: publicConfig(live()).statsPath,
             })
           }
         } catch (err) {
@@ -279,7 +279,7 @@ export function apply(ctx, config) {
               totalTokens: promptTokens + completionTokens,
               isError: true,
               is429: status === 429,
-              statsPath: live().statsPath,
+              statsPath: publicConfig(live()).statsPath,
             })
             if (status === 429 || isQuotaExceededError(msg)) {
               handleStream429()

package/lib/provider-sync.js

@@ -21,10 +21,26 @@ import { publicConfig, plainConfig, Config, LLM_PI_AI_NS } from './config.js'
 import { publicUsage } from './http.js'
 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'
 
 export function resolvePathWithHome(p) {
-  if (typeof p === 'string' && p.startsWith('~/')) {
-    return path.join(os.homedir(), p.slice(2))
+  let guard = 0
+  while (guard < 5 && p) {
+    if (typeof p === 'function') {
+      try { p = p() } catch { p = ''; break }
+      guard += 1
+    } else if (typeof p === 'object' && typeof p.get === 'function') {
+      try { p = p.get() } catch { p = ''; break }
+      guard += 1
+    } else {
+      break
+    }
+  }
+  if (typeof p !== 'string') return ''
+  if (p.startsWith('~/') || p === '~') {
+    const home = process.env.HOME || os.homedir()
+    return path.join(home, p.slice(1))
   }
   return p
 }
@@ -183,13 +199,24 @@ export async function upsertPiAiProvider(ctx, cfg, activeModelIds) {
   const activeAcc = await resolveActiveAccountKey(ctx, cfg)
 
   const port = ctx?.webServer?.port || process.env.PORT || 3080
-  const effectiveBaseUrl = pub.proxyMode !== false
+  const isProxy = pub.proxyMode !== false
+  const effectiveBaseUrl = isProxy
     ? `http://127.0.0.1:${port}/dsh-clinebot/v1`
     : pub.baseUrl
 
+  const localToken = isProxy ? getLocalProxyToken() : undefined
+  if (isProxy && localToken) {
+    try {
+      await saveCredentialKey(ctx, LOCAL_PROXY_KEY_ENV, localToken)
+    } catch {
+      /* credentials service might be absent/read-only in tests; process.env is set */
+    }
+  }
+
   const providerObj = buildPiAiProvider({
     baseUrl: effectiveBaseUrl,
     apiKeyEnv: activeAcc?.apiKeyEnv || pub.apiKeyEnv,
+    apiKey: localToken,
     models: modelsToRegister.length ? modelsToRegister : allModels,
     customModels: [...(pub.dynamicModels || []), ...(pub.customModels || [])],
     displayName: PROVIDER_DISPLAY_NAME,

package/lib/proxy-token.js

@@ -0,0 +1,42 @@
+/**
+ * Local Proxy Authentication Token (Issue #145)
+ *
+ * Secures transparent proxy endpoints (/dsh-clinebot/v1/*) from unauthorized
+ * LAN clients or cross-site browser requests (CSRF).
+ */
+
+import crypto from 'node:crypto'
+
+export const LOCAL_PROXY_KEY_ENV = 'CLINEBOT_LOCAL_PROXY_TOKEN'
+
+let cachedToken = null
+
+/**
+ * Get or generate the local proxy bearer token.
+ *
+ * @returns {string}
+ */
+export function getLocalProxyToken() {
+  if (cachedToken) return cachedToken
+  if (process.env[LOCAL_PROXY_KEY_ENV]) {
+    cachedToken = process.env[LOCAL_PROXY_KEY_ENV]
+    return cachedToken
+  }
+  cachedToken = crypto.randomBytes(24).toString('hex')
+  process.env[LOCAL_PROXY_KEY_ENV] = cachedToken
+  return cachedToken
+}
+
+/**
+ * Manually set local proxy token (for testing).
+ *
+ * @param {string|null} token
+ */
+export function setLocalProxyToken(token) {
+  cachedToken = token
+  if (token) {
+    process.env[LOCAL_PROXY_KEY_ENV] = token
+  } else {
+    delete process.env[LOCAL_PROXY_KEY_ENV]
+  }
+}

package/lib/routes/proxy.js

@@ -1,23 +1,56 @@
 /**
- * Transparent Loopback Proxy & Zero-Downtime Failover (Issue #127)
+ * Transparent Loopback Proxy & Zero-Downtime Failover (Issues #127, #145, #147)
  *
  * Exposes local OpenAI-compatible endpoints:
  * - POST /dsh-clinebot/v1/chat/completions
  * - GET  /dsh-clinebot/v1/models
  *
  * Implements:
- * 1. Sticky session routing with least-used quota allocation.
- * 2. Transparent upstream retry on 429 / quota exhaustion before first chunk is streamed.
- * 3. Accurate streaming SSE token usage interception & persistent telemetry recording.
- * 4. Model reasoning_effort default injection from config.
+ * 1. Bearer local proxy token verification (Issue #145).
+ * 2. Origin & Sec-Fetch-Site rejection to prevent cross-site/browser CSRF attacks (Issue #145).
+ * 3. Dynamic User-Agent extraction from package.json (Issue #147).
+ * 4. Configurable upstream timeout with multi-account failover and 504 handling (Issue #147).
+ * 5. Sticky session routing with least-used quota allocation.
+ * 6. Streaming SSE token usage interception & persistent telemetry recording.
  */
 
+import { createRequire } from 'node:module'
 import { writeJson, readBody, isLoopbackAddress } from '../http.js'
 import { publicConfig, plainConfig } from '../config.js'
 import { resolveAccountPool } from '../account-pool.js'
 import { resolveSessionAccount, markAccountCooldown } from '../session-router.js'
 import { recordUsage } from '../stats-storage.js'
 import { getAllModels, DEFAULT_MODEL_ID } from '../models.js'
+import { getLocalProxyToken } from '../proxy-token.js'
+
+const require = createRequire(import.meta.url)
+let packageVersion = '0.5.2'
+try {
+  packageVersion = require('../../package.json').version || '0.5.2'
+} catch (err) {
+  /* fallback to default version if manifest is unreadable */
+}
+
+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
+}
+
+export function isAuthorizedProxyRequest(req) {
+  const auth = req.headers?.['authorization'] || ''
+  const match = auth.match(/^Bearer\s+(.+)$/i)
+  if (!match) return false
+  const token = match[1].trim()
+  return Boolean(token && token === getLocalProxyToken())
+}
 
 export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderState }) {
   // 1. POST /dsh-clinebot/v1/chat/completions
@@ -33,9 +66,17 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
         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' })
+      }
+
+      if (!isAuthorizedProxyRequest(req)) {
+        return writeJson(res, 401, { ok: false, error: 'Unauthorized: missing or invalid bearer token' })
+      }
+
       let bodyBuf
       try {
-        bodyBuf = await readBody(req)
+        bodyBuf = await readBody(req, 64 * 1024 * 1024)
       } catch (err) {
         return writeJson(res, 400, { ok: false, error: String(err?.message || err) })
       }
@@ -72,19 +113,20 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
         body.reasoning_effort = pub.modelReasoningDefaults[body.model]
       }
 
+      const isStreaming = Boolean(body.stream)
       const pool = await resolveAccountPool(ctx, cfg)
-      const isStreaming = Boolean(body.stream) || String(req.headers.accept || '').includes('text/event-stream')
+      const configuredAccounts = pool.filter(a => a.present && a.value)
 
-      // Transparent retry loop (up to max configured accounts, min 1, max 3)
-      const maxRetries = Math.min(Math.max(1, pool.length), 3)
+      const maxRetries = Math.max(1, configuredAccounts.length)
       let attempt = 0
       let lastError = null
-      let targetAccount = null
+      let hadTimeout = false
 
       while (attempt < maxRetries) {
-        attempt++
+        attempt += 1
+
         const routeResult = resolveSessionAccount(sessionId, pool, pub.activeAccount)
-        targetAccount = routeResult.account
+        const targetAccount = routeResult.account
 
         if (!targetAccount || !targetAccount.value) {
           return writeJson(res, 503, {
@@ -101,8 +143,19 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           'Content-Type': 'application/json',
           'Authorization': `Bearer ${targetAccount.value}`,
           'Accept': isStreaming ? 'text/event-stream' : 'application/json',
-          'User-Agent': '@goodandready/dsh-clinebot/0.5.0'
+          '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])
 
         let upstreamRes
         try {
@@ -110,15 +163,26 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
             method: 'POST',
             headers: requestHeaders,
             body: JSON.stringify(body),
+            signal: fetchSignal,
             keepalive: true
           })
         } catch (fetchErr) {
+          if (clientAbortCtrl.signal.aborted) {
+            // Client closed connection, stop processing
+            return
+          }
           lastError = fetchErr
-          // Network errors: retry with next account if available
+          const isTimeout = timeoutSignal.aborted || fetchErr.name === 'TimeoutError' || String(fetchErr).includes('timeout')
+          if (isTimeout) {
+            hadTimeout = true
+            const accountId = 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})`)
+          }
           continue
         }
 
-        // If upstream rejected with 429 or 403 quota exhaustion before streaming, failover!
+        // 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
           markAccountCooldown(accountId, 60000, null, 'upstream_429')
@@ -152,7 +216,7 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
           const decoder = new TextDecoder('utf8')
 
           let streamAborted = false
-          const onClientAbort = () => {
+          const onStreamAbort = () => {
             streamAborted = true
             try {
               reader.cancel().catch(() => {})
@@ -161,7 +225,7 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
             }
           }
           if (typeof req.on === 'function') {
-            req.on('close', onClientAbort)
+            req.on('close', onStreamAbort)
           }
 
           try {
@@ -175,47 +239,48 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
               // Parse SSE lines for usage metrics
               buffer += chunkStr
               const lines = buffer.split('\n')
-              buffer = lines.pop() // keep incomplete last line
+              buffer = lines.pop() || ''
 
               for (const line of lines) {
                 const trimmed = line.trim()
-                if (trimmed.startsWith('data: ') && trimmed !== 'data: [DONE]') {
+                if (trimmed.startsWith('data:') && trimmed !== 'data: [DONE]') {
                   try {
-                    const data = JSON.parse(trimmed.slice(6))
-                    if (data?.usage) {
-                      promptTokens = Number(data.usage.prompt_tokens) || promptTokens
-                      completionTokens = Number(data.usage.completion_tokens) || completionTokens
-                      totalTokens = Number(data.usage.total_tokens) || totalTokens
+                    const parsed = JSON.parse(trimmed.slice(5).trim())
+                    if (parsed.usage) {
+                      promptTokens = parsed.usage.prompt_tokens || promptTokens
+                      completionTokens = parsed.usage.completion_tokens || completionTokens
+                      totalTokens = parsed.usage.total_tokens || totalTokens
                     }
                   } catch {
-                    /* ignore partial or non-json SSE lines */
+                    /* ignore JSON chunk parse error */
                   }
                 }
               }
             }
           } catch (streamErr) {
-            if (!streamAborted) {
-              ctx?.logger?.warn?.(`[dsh-clinebot:proxy] Error streaming SSE chunk: ${streamErr?.message || streamErr}`)
-            }
+            ctx?.logger?.warn?.('[dsh-clinebot:proxy] Stream read error: ' + (streamErr?.message || streamErr))
           } finally {
-            if (typeof req.off === 'function') {
-              req.off('close', onClientAbort)
+            try {
+              reader.releaseLock()
+            } catch (err) {
+              /* ignore lock release error if reader already closed */
             }
             res.end()
+
             recordUsage({
               model: body.model,
               accountId: targetAccount.id || targetAccount.label,
               promptTokens,
               completionTokens,
-              totalTokens,
+              totalTokens: totalTokens || (promptTokens + completionTokens),
               statsPath: pub.statsPath
             })
           }
           return
         }
 
-        // Non-streaming JSON response or error status from upstream
-        const resText = await upstreamRes.text()
+        // Non-streaming JSON response
+        const resText = await upstreamRes.text().catch(() => '{}')
         let resJson = null
         try {
           resJson = JSON.parse(resText)
@@ -242,6 +307,16 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
       }
 
       // Exhausted all retries
+      if (hadTimeout) {
+        return writeJson(res, 504, {
+          error: {
+            message: 'Gateway Timeout: upstream provider timed out across all available accounts',
+            type: 'gateway_timeout',
+            code: 'upstream_timeout'
+          }
+        })
+      }
+
       writeJson(res, 429, {
         error: {
           message: 'All configured accounts in pool exceeded rate limits or quota',
@@ -265,6 +340,15 @@ export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderSta
       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' })
+      }
+
+      if (!isAuthorizedProxyRequest(req)) {
+        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 : []

package/lib/stats-storage.js

@@ -40,12 +40,39 @@ export function createEmptyStats() {
 /**
  * Resolve '~' in paths to user's home directory.
  */
+/**
+ * Get active .dsh directory, respecting DSH_HOME and HOME environment variables.
+ *
+ * @returns {string}
+ */
+export function getDshHome() {
+  if (process.env.DSH_HOME) return process.env.DSH_HOME
+  const home = process.env.HOME || homedir()
+  return path.join(home, '.dsh')
+}
+
 export function resolvePath(targetPath) {
+  let unwrapGuard = 0
+  while (unwrapGuard < 5 && targetPath) {
+    if (typeof targetPath === 'function') {
+      try { targetPath = targetPath() } catch { targetPath = ''; break }
+      unwrapGuard += 1
+    } else if (typeof targetPath === 'object' && typeof targetPath.get === 'function') {
+      try { targetPath = targetPath.get() } catch { targetPath = ''; break }
+      unwrapGuard += 1
+    } else {
+      break
+    }
+  }
+  if (typeof targetPath !== 'string') {
+    targetPath = ''
+  }
   if (!targetPath) {
-    return path.join(homedir(), '.dsh', 'clinebot-stats.json')
+    return path.join(getDshHome(), 'clinebot-stats.json')
   }
   if (targetPath.startsWith('~/') || targetPath === '~') {
-    return path.join(homedir(), targetPath.slice(1))
+    const home = process.env.HOME || homedir()
+    return path.join(home, targetPath.slice(1))
   }
   return path.resolve(targetPath)
 }
@@ -57,10 +84,9 @@ export function resolvePath(targetPath) {
  * @returns {Object} Loaded stats
  */
 export function loadStats(customPath) {
-  const filePath = resolvePath(customPath)
-  activeStatsPath = filePath
-
   try {
+    const filePath = resolvePath(customPath)
+    activeStatsPath = filePath
     if (existsSync(filePath)) {
       const raw = readFileSync(filePath, 'utf8')
       const parsed = JSON.parse(raw)
@@ -91,10 +117,10 @@ export function loadStats(customPath) {
  * @param {string} [customPath]
  */
 export function saveStatsSync(customPath) {
-  const filePath = resolvePath(customPath || activeStatsPath)
-  activeStatsPath = filePath
-
   try {
+    const filePath = resolvePath(customPath || activeStatsPath)
+    activeStatsPath = filePath
+
     const dir = path.dirname(filePath)
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true })
@@ -123,7 +149,11 @@ function queueSaveStats(customPath, debounceMs = 500) {
   }
   saveTimer = setTimeout(() => {
     saveTimer = null
-    saveStatsSync(customPath)
+    try {
+      saveStatsSync(customPath)
+    } catch {
+      // Best-effort disk persistence, never crash host process
+    }
   }, debounceMs)
 }
 

package/lib/updater.js

@@ -4,7 +4,7 @@
  */
 
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, unlinkSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, resolve } from 'node:path'
@@ -170,6 +170,41 @@ async function readCurrentVersion(manifestUrl) {
   return value.version
 }
 
+export function isPidAlive(pid) {
+  if (!pid || typeof pid !== 'number' || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err.code === 'EPERM'
+  }
+}
+
+export function checkProfileLock(profileDir) {
+  if (!profileDir) return { locked: false }
+  const lockFile = resolve(profileDir, 'package.json.lock')
+  if (!existsSync(lockFile)) return { locked: false }
+  try {
+    const content = readFileSync(lockFile, 'utf8')
+    const pid = parseInt(content.trim(), 10)
+    if (!Number.isNaN(pid) && pid > 0) {
+      if (isPidAlive(pid)) {
+        return { locked: true, pid, alive: true }
+      } else {
+        try {
+          unlinkSync(lockFile)
+        } catch (err) {
+          /* best-effort cleanup of stale lock */
+        }
+        return { locked: false, stalePid: pid }
+      }
+    }
+  } catch {
+    /* lock cannot be read */
+  }
+  return { locked: false }
+}
+
 export async function checkUpdateStatus(options, target = detectRuntime()) {
   const current = await readCurrentVersion(options.manifestUrl)
   const latest = await fetchLatestVersion(options.packageName, options.registry || 'https://registry.npmjs.org')
@@ -189,7 +224,7 @@ async function installExact(target, packageSpec, options) {
   await new Promise((resolvePromise, reject) => {
     const child = spawn(process.execPath, [
       target.cliEntry, 'plugin', '--profile', target.profileName, 'add',
-      '--config.minimumReleaseAge=0', packageSpec,
+      packageSpec,
       `--registry=${options.registry || 'https://registry.npmjs.org/'}`,
     ], {
       cwd: target.profileDir,
@@ -201,7 +236,31 @@ async function installExact(target, packageSpec, options) {
     child.stdout?.on('data', (chunk) => { detail = (detail + String(chunk)).slice(-4000) })
     child.stderr?.on('data', (chunk) => { detail = (detail + String(chunk)).slice(-4000) })
     const timer = setTimeout(() => {
-      child.kill()
+      child.kill('SIGTERM')
+      setTimeout(() => {
+        if (!child.killed) {
+          try {
+            child.kill('SIGKILL')
+          } catch (err) {
+            /* ignore if process already terminated */
+          }
+        }
+        setTimeout(() => {
+          if (target.profileDir) {
+            const lockFile = resolve(target.profileDir, 'package.json.lock')
+            if (existsSync(lockFile)) {
+              try {
+                const pid = parseInt(readFileSync(lockFile, 'utf8').trim(), 10)
+                if (!isPidAlive(pid)) {
+                  unlinkSync(lockFile)
+                }
+              } catch (err) {
+                /* best-effort stale lock unlink */
+              }
+            }
+          }
+        }, 100)
+      }, 500)
       reject(new Error('Update timed out.'))
     }, UPDATE_TIMEOUT_MS)
     child.once('error', (error) => { clearTimeout(timer); reject(error) })
@@ -248,6 +307,15 @@ export function registerPluginUpdater(ctx, options) {
           writeResponseJson(response, 409, { ok: false, error: 'This plugin is already updating.' })
           return
         }
+        const lockInfo = checkProfileLock(target.profileDir)
+        if (lockInfo.locked && lockInfo.alive) {
+          writeResponseJson(response, 409, {
+            ok: false,
+            error: `Another package installation is currently in progress (PID: ${lockInfo.pid}).`,
+            pid: lockInfo.pid
+          })
+          return
+        }
         installing = true
         try {
           const before = await checkUpdateStatus(options, target)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",
@@ -39,7 +39,7 @@
   },
   "scripts": {
     "build:client": "node scripts/build-client.js",
-    "test": "node scripts/build-client.js && node --test test/*.test.js"
+    "test": "node scripts/build-client.js && node --import ./test/_setup.mjs --test test/*.test.js"
   },
   "engines": {
     "node": ">=20"