@goodandready/dsh-clinebot 0.5.8 → 0.5.9

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.9] - 2026-10-01
+
+### Fixed
+- **Updater Timeout Exit & SIGKILL Escalation (Issue #172)**: Ensured `installExact` child process cleanup waits for the operating system process to fully terminate via `exit`/`close` events before releasing profile locks or rejecting update promises. On timeout, sends `SIGTERM`, waits for a grace period, and escalates to `SIGKILL` for stubborn subprocesses.
+- **Proxy Client Disconnection SSE Abort Fixture (Issue #173)**: Validated client disconnection handling against a real Node.js loopback HTTP fixture with client TCP stream destruction, asserting upstream `reader.cancel()` and fetch `signal.aborted` without relying exclusively on synthetic mocks.
+- **Dependency Manifest & Lockfile Synchronization (Issue #174)**: Regenerated `package-lock.json` via clean npm resolution for all 21 dependencies to ensure deterministic, clean `npm ci` builds across environments, while maintaining proper exclusion of the lockfile from package archives.
+- **UI Locale Key Completeness & Reasoning/Quota Strings (Issue #175)**: Resolved missing locale keys across `en` and `zh` dictionaries for structured quota countdowns/warnings, reasoning tags and effort selectors, capability badges, smoke test diagnostic outputs, and ErrorBoundary alerts. Added regression test asserting 100% dictionary completeness and symmetry for client `t()` calls.
+- **Update Check State Machine & Error Handling (Issue #176)**: Implemented explicit update state machine (`idle`, `checking`, `current`, `available`, `error`) in `UpdateBanner` and `settings-page.js`. Eliminated false "✓ Up to date" status indicators on failed network checks or when `latestCheckFailed: true`, and added retry action.
+- **Documentation & Design Contract Modernization (Issue #177)**: Synchronized `README.md`, `README.ru.md`, `README.zh.md`, and `docs/design/DESIGN.md` with active runtime contracts: documented dynamic subscription catalog, custom models, active configuration schema (`disabledModels`, `proxyMode`, `accounts`), corrected route prefixes (`/dsh-clinebot/*`), and documented all 4 registered UI seats and release testing workflows.
+
 ## [0.5.8] - 2026-09-30
 
 ### Fixed

package/README.md

@@ -74,7 +74,7 @@ graph LR
     end
 
     subgraph PluginHost [dsh-clinebot Host Runtime]
-        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        HttpEndpoints["API: /dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
         ModelCatalog["lib/models.js (Curated + Dynamic Plan)"]
         SlashCmd["Command: /cline"]
@@ -108,7 +108,7 @@ graph LR
 ## ✨ Features & Module Breakdown
 
 * **`lib/models.js`**:
-  Manages the curated catalog (11 built-in models) with full reasoning effort mappings (`off: null`, `low`, `medium`, `high`, `max`), upstream 200k context limit declarations, and dynamic subscription plan model parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+  Manages the dynamic subscription catalog and fallback models with full reasoning effort mappings (`off: null`, `low`, `medium`, `high`, `max`), upstream 200k context limit declarations, user-defined custom models, and dynamic subscription plan model parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
 * **`lib/cline-client.js`**:
   * `fetchUsageLimits`: queries `GET /users/me/plan/usage-limits`, `GET /users/me/plan`, and `GET /users/me` with in-memory caching.
   * `sessionStats` / `recordSessionRequest`: in-memory telemetry recording requests count, tokens, latency, and timestamps.
@@ -163,29 +163,42 @@ dsh-clinebot:
   enabled: true
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
-  defaultModel: cline-pass/deepseek-v4-flash
-  timeoutMs: 15000
-  smokeTimeoutMs: 25000
-  enabledModels:
-    - cline-pass/deepseek-v4-flash
-    - cline-pass/deepseek-v4-pro
-    - cline-pass/kimi-k3
-    - cline-pass/qwen3.7-max
-  dynamicModels: []
+  defaultModel: your-default-model
+  proxyMode: true
+  disabledModels: []
+  customModels: []
+  modelReasoningDefaults:
+    your-reasoning-model: high
+  modelContextOverrides: []
+  statsPath: ~/.dsh/clinebot-stats.json
+  timeoutMs: 30000
+  smokeTimeoutMs: 60000
+  streamIdleTimeoutMs: 60000
+  accounts:
+    - label: Team Key
+      apiKeyEnv: CLINEBOT_API_KEY_2
 ```
 
 ### Configuration Parameters
 
 | Parameter | Type | Default | Description |
 |:---|:---|:---|:---|
-| `enabled` | `boolean` | `true` | Enable or disable the ClineBot provider bridge |
+| `enabled` | `boolean` | `true` | Enable or disable the ClineBot provider bridge in DSH |
 | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI-compatible base URL |
 | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Environment variable / credentials key name |
-| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Default selected model ID |
+| `defaultModel` | `string` | `"claude-3-7-sonnet"` | Default selected model ID for chat and smoke tests |
+| `disabledModels` | `array` | `[]` | List of model IDs hidden from the DSH chat picker (new subscription models are auto-enabled) |
+| `customModels` | `array` | `[]` | User-defined gateway models (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
+| `modelReasoningDefaults` | `object` | `{}` | Configured default reasoning effort per model (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | User-defined model context length and max token overrides |
-| `timeoutMs` | `number` | `15000` | HTTP request timeout in milliseconds |
-| `smokeTimeoutMs` | `number` | `25000` | Smoke test latency ping timeout |
-| `enabledModels` | `array` | `[...]` | List of models exposed in the DSH chat picker |
+| `proxyMode` | `boolean` | `true` | Enable local transparent loopback proxy for sticky sessions and automatic 429 failover |
+| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Persistent on-disk path for token usage analytics |
+| `accounts` | `array` | `[]` | Additional accounts for multi-account failover and quota rotation (`[{ label, apiKeyEnv }]`) |
+| `activeAccount` | `string` | `""` | Manually pinned active account env name (empty for least-used auto routing) |
+| `timeoutMs` | `number` | `30000` | HTTP probe timeout in milliseconds |
+| `smokeTimeoutMs` | `number` | `60000` | Timeout for smoke test chat completions in milliseconds |
+| `streamIdleTimeoutMs` | `number` | `60000` | Idle timeout between SSE stream chunks in milliseconds |
+| `enabledModels` | `array` | *(deprecated)* | Read-only in public config; rejected on `PUT /config` in favor of `disabledModels` |
 | `dynamicModels` | `array` | `[]` | Dynamic models automatically synced from the official plan |
 
 ---

package/README.ru.md

@@ -74,7 +74,7 @@ graph LR
     end
 
     subgraph PluginHost [Хост-часть dsh-clinebot]
-        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        HttpEndpoints["API: /dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
         ModelCatalog["lib/models.js (Встроенные + Динамические из плана)"]
         SlashCmd["Слэш-команда: /cline"]
@@ -107,7 +107,7 @@ graph LR
 
 ## ✨ Структура модулей и возможности
 
-* **`lib/models.js`**: каталог встроенных моделей ClinePass (11 моделей с полной поддержкой уровней размышлений `Off` / `Low` / `Medium` / `High` / `Max` и фиксацией лимита шлюза в 200k токенов) и парсер моделей подписки (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+* **`lib/models.js`**: динамический каталог моделей подписки и встроенных шаблонов с поддержкой уровней рассуждения (`Off` / `Low` / `Medium` / `High` / `Max`), контекстных лимитов, пользовательских моделей (`customModels`) и парсинга тарифа (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
 * **`lib/cline-client.js`**:
   * `fetchUsageLimits`: параллельный опрос `GET /users/me/plan/usage-limits`, `GET /users/me/plan` и `GET /users/me` с кэшированием в памяти.
   * `sessionStats` / `recordSessionRequest`: счетчики сессии (запросы, токены, задержка, время).
@@ -158,29 +158,42 @@ dsh-clinebot:
   enabled: true
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
-  defaultModel: cline-pass/deepseek-v4-flash
-  timeoutMs: 15000
-  smokeTimeoutMs: 25000
-  enabledModels:
-    - cline-pass/deepseek-v4-flash
-    - cline-pass/deepseek-v4-pro
-    - cline-pass/kimi-k3
-    - cline-pass/qwen3.7-max
-  dynamicModels: []
+  defaultModel: your-default-model
+  proxyMode: true
+  disabledModels: []
+  customModels: []
+  modelReasoningDefaults:
+    your-reasoning-model: high
+  modelContextOverrides: []
+  statsPath: ~/.dsh/clinebot-stats.json
+  timeoutMs: 30000
+  smokeTimeoutMs: 60000
+  streamIdleTimeoutMs: 60000
+  accounts:
+    - label: Team Key
+      apiKeyEnv: CLINEBOT_API_KEY_2
 ```
 
 ### Параметры конфигурации
 
 | Параметр | Тип | По умолчанию | Описание |
 |:---|:---|:---|:---|
-| `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot |
+| `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot в DSH |
 | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | Базовый URL OpenAI-совместимого API ClinePass |
 | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Имя переменной / ключа в хранилище credentials |
-| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Модель, выбираемая по умолчанию |
+| `defaultModel` | `string` | `"claude-3-7-sonnet"` | Модель, выбираемая по умолчанию для чата и smoke-тестов |
+| `disabledModels` | `array` | `[]` | Список отключённых моделей (новые модели подписки включаются автоматически) |
+| `customModels` | `array` | `[]` | Пользовательские модели шлюза (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
+| `modelReasoningDefaults` | `object` | `{}` | Значения thinking effort по умолчанию для моделей (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | Пользовательские переопределения размера контекста и лимита токенов |
-| `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) |
-| `smokeTimeoutMs` | `number` | `25000` | Таймаут тестового пинга (мс) |
-| `enabledModels` | `array` | `[...]` | Список моделей, активных в селекторе чата |
+| `proxyMode` | `boolean` | `true` | Включение локального прозрачного loopback-прокси с сессионным роутингом и failover |
+| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Путь к файлу персистентной аналитики использования токенов |
+| `accounts` | `array` | `[]` | Дополнительные аккаунты для ротации квоты и failover (`[{ label, apiKeyEnv }]`) |
+| `activeAccount` | `string` | `""` | Принудительно закреплённый аккаунт (пусто для автоматического выбора least-used) |
+| `timeoutMs` | `number` | `30000` | Таймаут HTTP-запросов (мс) |
+| `smokeTimeoutMs` | `number` | `60000` | Таймаут тестового пинга инференса (мс) |
+| `streamIdleTimeoutMs` | `number` | `60000` | Таймаут ожидания между чанками SSE-потока (мс) |
+| `enabledModels` | `array` | *(устарело)* | Только для чтения в public config; отклоняется при `PUT /config` в пользу `disabledModels` |
 | `dynamicModels` | `array` | `[]` | Динамические модели, автоматически синхронизированные из тарифа |
 
 ---

package/README.zh.md

@@ -74,7 +74,7 @@ graph LR
     end
 
     subgraph PluginHost [dsh-clinebot 宿主运行环境]
-        HttpEndpoints["API 路由: /api/plugins/dsh-clinebot/*"]
+        HttpEndpoints["API 路由: /dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
         ModelCatalog["lib/models.js (内置精选 + 动态订阅解析)"]
         SlashCmd["斜杠指令: /cline"]
@@ -107,7 +107,7 @@ graph LR
 
 ## ✨ 核心模块与功能
 
-* **`lib/models.js`**：管理 11 款官方精选内置模型（提供完整的 `Off` / `Low` / `Medium` / `High` / `Max` 思考强度映射、上游 200k 上下文容量标注）以及套餐模型动态解析器（`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`）。
+* **`lib/models.js`**：管理动态订阅模型目录与内置精选模板（提供完整的 `Off` / `Low` / `Medium` / `High` / `Max` 思考强度映射、上游 200k 上下文容量标注、自定义模型支持）以及套餐模型动态解析器（`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`）。
 * **`lib/cline-client.js`**：
   * `fetchUsageLimits`：高效并发轮询 `GET /users/me/plan/usage-limits`、`GET /users/me/plan` 与 `GET /users/me` 并进行内存缓存。
   * `sessionStats` / `recordSessionRequest`：内存级会话度量记录器（请求次数、Token 估算、延迟、时间戳）。
@@ -160,29 +160,42 @@ dsh-clinebot:
   enabled: true
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
-  defaultModel: cline-pass/deepseek-v4-flash
-  timeoutMs: 15000
-  smokeTimeoutMs: 25000
-  enabledModels:
-    - cline-pass/deepseek-v4-flash
-    - cline-pass/deepseek-v4-pro
-    - cline-pass/kimi-k3
-    - cline-pass/qwen3.7-max
-  dynamicModels: []
+  defaultModel: your-default-model
+  proxyMode: true
+  disabledModels: []
+  customModels: []
+  modelReasoningDefaults:
+    your-reasoning-model: high
+  modelContextOverrides: []
+  statsPath: ~/.dsh/clinebot-stats.json
+  timeoutMs: 30000
+  smokeTimeoutMs: 60000
+  streamIdleTimeoutMs: 60000
+  accounts:
+    - label: Team Key
+      apiKeyEnv: CLINEBOT_API_KEY_2
 ```
 
 ### 配置参数说明
 
 | 参数项 | 类型 | 默认值 | 说明 |
 |:---|:---|:---|:---|
-| `enabled` | `boolean` | `true` | 是否启用 ClineBot 桥接插件 |
+| `enabled` | `boolean` | `true` | 是否在 DSH 中启用 ClineBot 桥接插件 |
 | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI 兼容接口地址 |
 | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | 凭据管理系统中的密钥名称 |
-| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | 默认选中的模型 ID |
+| `defaultModel` | `string` | `"claude-3-7-sonnet"` | 默认选中的模型 ID（用于对话及探活） |
+| `disabledModels` | `array` | `[]` | 在选择器中隐藏的模型 ID 列表（新订阅模型默认自动启用） |
+| `customModels` | `array` | `[]` | 用户自定义网关模型 (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
+| `modelReasoningDefaults` | `object` | `{}` | 各模型默认思考强度配置 (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | 用户自定义模型上下文窗口与最大 Token 数量覆盖 |
-| `timeoutMs` | `number` | `15000` | HTTP 请求超时时间（毫秒） |
-| `smokeTimeoutMs` | `number` | `25000` | 探活测试超时时间（毫秒） |
-| `enabledModels` | `array` | `[...]` | 允许在聊天下拉框中显示的可用模型列表 |
+| `proxyMode` | `boolean` | `true` | 启用透明本地环回代理以支持会话粘性路由与 429 自动故障转移 |
+| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | 本地持久化 Token 用量统计文件路径 |
+| `accounts` | `array` | `[]` | 额外轮转账号池 (`[{ label, apiKeyEnv }]`) |
+| `activeAccount` | `string` | `""` | 手动指定的主账号（为空时自动按最低配额消耗优先路由） |
+| `timeoutMs` | `number` | `30000` | HTTP 请求探测超时时间（毫秒） |
+| `smokeTimeoutMs` | `number` | `60000` | 探活测试超时时间（毫秒） |
+| `streamIdleTimeoutMs` | `number` | `60000` | SSE 流式输出块间空闲超时时间（毫秒） |
+| `enabledModels` | `array` | *(已废弃)* | 仅在 public config 中只读提供，`PUT /config` 时禁止写入并请使用 `disabledModels` |
 | `dynamicModels` | `array` | `[]` | 从官方套餐中自动同步的动态模型列表 |
 
 ---

package/lib/client.js

@@ -24,6 +24,19 @@ function readConfigForms(ctx) {
   try { return ctx.get('configForms') || undefined } catch { return undefined }
 }
 
+function useConfigFormsSnapshot(ctx) {
+  const scope = React.useMemo(() => {
+    try { return readConfigForms(ctx)?.get?.(NS) || undefined } catch { return undefined }
+  }, [ctx])
+  const subscribe = React.useMemo(() => (cb) => {
+    try { return scope?.subscribe ? (scope.subscribe(cb) || (() => {})) : () => {} } catch { return () => {} }
+  }, [scope])
+  const getSnapshot = React.useCallback(() => {
+    try { return scope?.getSnapshot?.() || SNAPSHOT_READY } catch { return SNAPSHOT_READY }
+  }, [scope])
+  return React.useSyncExternalStore(subscribe, getSnapshot, () => SNAPSHOT_READY)?.status || 'loading'
+}
+
 // --- src/client/locales.js ---
 const en = {
       title: 'ClineBot',
@@ -79,6 +92,27 @@ const en = {
       'quota.window_weekly': '📅 Weekly Window',
       'quota.used': '{pct}% used',
       'quota.reset_at': 'Reset: {time}',
+      'quota.window_monthly': '📅 Monthly Window',
+      'quota.countdown': 'Resets in {time}',
+      'quota.warning_low': 'Quota is below 10%. Requests may be throttled soon.',
+      'quota.exhausted_5h': '5-hour rolling limit is almost exhausted ({percentUsed}%). New requests may be rejected until quota reset.',
+      'quota.warning_5h': 'Low quota warning: {percentUsed}% of 5-hour limit consumed (<10% remaining).',
+      'quota.warning_weekly': 'Low weekly quota warning: {percentUsed}% consumed ({remainingPercent}% remaining).',
+      'quota.warning_monthly': 'Low monthly quota warning: {percentUsed}% consumed ({remainingPercent}% remaining).',
+      'models.reasoning_tag': '🧠 Reasoning',
+      'models.effort_low': 'Low',
+      'models.effort_medium': 'Medium',
+      'models.effort_high': 'High',
+      'models.effort_max': 'Max',
+      'models.caps_vision': 'Vision',
+      'models.caps_general': 'General',
+      'models.caps_coding': 'Coding',
+      'diag.smoke_result': '✅ Latency: {latency} ms | Model: {model}\nResponse: {preview}',
+      'diag.empty': '(empty)',
+      'ui.error_title': '⚠️ ClineBot UI Error: ',
+      'ui.retry': 'Retry',
+      'update.check_failed': 'Failed to check for updates',
+      'update.retry': 'Retry check',
       'models.title': '🎯 Model Picker in DSH ({enabled} of {total} active)',
       'models.desc': 'Catalog synchronizes directly from ClinePass subscription. New plan models are enabled automatically. Uncheck models to hide them from DSH chat picker. Thinking effort is selectable in the composer model menu.',
       'models.reasoning_tooltip': 'Supports thinking effort selection in composer model menu (Off / Low / Medium / High / Max)',
@@ -206,6 +240,27 @@ const en = {
       'quota.window_weekly': '📅 每周滚动窗口',
       'quota.used': '已使用 {pct}%',
       'quota.reset_at': '重置时间：{time}',
+      'quota.window_monthly': '📅 每月滚动窗口',
+      'quota.countdown': '{time}后重置',
+      'quota.warning_low': '额度低于 10%，请求可能很快会受到限制。',
+      'quota.exhausted_5h': '5 小时滚动限额已接近耗尽（已用 {percentUsed}%）。在额度重置前新请求可能会被拒绝。',
+      'quota.warning_5h': '低额度警告：5 小时限额已消耗 {percentUsed}%（剩余不足 10%）。',
+      'quota.warning_weekly': '周限额偏低警告：已消耗 {percentUsed}%（剩余 {remainingPercent}%）。',
+      'quota.warning_monthly': '月限额偏低警告：已消耗 {percentUsed}%（剩余 {remainingPercent}%）。',
+      'models.reasoning_tag': '🧠 深度思考',
+      'models.effort_low': '低',
+      'models.effort_medium': '中',
+      'models.effort_high': '高',
+      'models.effort_max': '最高',
+      'models.caps_vision': '视觉',
+      'models.caps_general': '通用',
+      'models.caps_coding': '编程',
+      'diag.smoke_result': '✅ 延迟：{latency} ms | 模型：{model}\n响应：{preview}',
+      'diag.empty': '(空)',
+      'ui.error_title': '⚠️ ClineBot 界面错误：',
+      'ui.retry': '重试',
+      'update.check_failed': '检查更新失败',
+      'update.retry': '重试检查',
       'models.title': '🎯 DSH 模型选择列表（已启用 {enabled}/{total}）',
       'models.desc': '模型目录与 ClinePass 官方订阅实时同步。新订阅模型默认自动启用。取消勾选可在 DSH 对话模型列表中隐藏不需要的模型。支持在对话输入框上方切换推理思考强度（Effort）。',
       'models.reasoning_tooltip': '支持在对话框上方模型菜单中选择思考强度（Off / Low / Medium / High / Max）',
@@ -399,10 +454,13 @@ function createErrorBoundary() {
       }
       render() {
         if (this.state.hasError) {
+          const t = this.props && typeof this.props.t === 'function' ? this.props.t : null
+          const errorTitle = t ? t('ui.error_title') : '⚠️ ClineBot UI Error: '
+          const retryLabel = t ? t('ui.retry') : 'Retry'
           return React.createElement(
             'div',
             { className: 'cb-alert-err' },
-            React.createElement('strong', null, '⚠️ ClineBot UI Error: '),
+            React.createElement('strong', null, errorTitle),
             String(this.state.error?.message || this.state.error || 'Unknown rendering error'),
             React.createElement(
               'button',
@@ -412,7 +470,7 @@ function createErrorBoundary() {
                 style: { marginLeft: '12px', padding: '2px 8px', fontSize: '11px' },
                 onClick: () => this.setState({ hasError: false, error: null }),
               },
-              'Retry'
+              retryLabel
             )
           )
         }
@@ -537,7 +595,22 @@ function ProgressBar({ label, percentUsed, remainingPercent, resetsAt, t }) {
 }
 
 // --- src/client/components/update-banner.js ---
-function UpdateBanner({ updateState, handleTriggerUpdate, t }) {
+function UpdateBanner({ updateState, handleTriggerUpdate, handleCheckUpdate, t }) {
+  const status = updateState.status || (
+    updateState.checking
+      ? 'checking'
+      : (updateState.latestCheckFailed
+          ? 'error'
+          : (updateState.updateAvailable
+              ? 'available'
+              : (updateState.lastCheckedAt ? 'current' : 'idle')))
+  )
+
+  const isChecking = status === 'checking' || updateState.checking
+  const isAvailable = status === 'available' || updateState.updateAvailable
+  const isCurrent = status === 'current'
+  const isError = status === 'error' || updateState.latestCheckFailed
+
   return React.createElement(
     React.Fragment,
     null,
@@ -561,19 +634,25 @@ function UpdateBanner({ updateState, handleTriggerUpdate, t }) {
               `v${updateState.currentVersion}`
             )
           : null,
-        updateState.checking
+        isChecking
           ? React.createElement('span', { style: { color: 'var(--dsw-alias-label-tertiary)', fontSize: '12px' } },
               t('update.checking')
             )
-          : updateState.updateAvailable
+          : isAvailable
             ? React.createElement('span', { className: 'cb-badge cb-badge-warn' },
                 t('update.available', { latestVersion: updateState.latestVersion, currentVersion: updateState.currentVersion })
               )
-            : React.createElement('span', { className: 'cb-badge cb-badge-ok' },
-                '✓ ' + t('update.up_to_date')
-              )
+            : isCurrent
+              ? React.createElement('span', { className: 'cb-badge cb-badge-ok' },
+                  '✓ ' + t('update.up_to_date')
+                )
+              : isError
+                ? React.createElement('span', { className: 'cb-badge cb-badge-bad' },
+                    t('update.check_failed')
+                  )
+                : null
       ),
-      updateState.updateAvailable
+      isAvailable
         ? React.createElement(
             'button',
             {
@@ -585,7 +664,19 @@ function UpdateBanner({ updateState, handleTriggerUpdate, t }) {
             },
             updateState.updating ? t('update.updating') : t('update.btn')
           )
-        : null
+        : isError && handleCheckUpdate
+          ? React.createElement(
+              'button',
+              {
+                type: 'button',
+                className: 'cb-btn',
+                disabled: isChecking,
+                onClick: handleCheckUpdate,
+                style: { padding: '5px 12px', fontSize: '12px' }
+              },
+              t('update.retry')
+            )
+          : null
     ),
     updateState.notice ? React.createElement('div', { className: 'cb-alert-ok' }, '✓ ' + updateState.notice) : null,
     updateState.error ? React.createElement('div', { className: 'cb-alert-err' }, updateState.error) : null
@@ -936,7 +1027,7 @@ function QuotaSection({ keyPresent, status, usage, busy, handleRefreshQuota, t }
           React.createElement(
             'div',
             { style: { flex: 1 } },
-            React.createElement('div', null, status.quotaWarning.message),
+            React.createElement('div', null, (status.quotaWarning.code && t(status.quotaWarning.code, status.quotaWarning.params)) || status.quotaWarning.message),
             status.quotaWarning.resetsAt
               ? React.createElement(
                   'div',
@@ -1552,19 +1643,20 @@ function ModelsSection({
                   m.category === 'reasoning'
                 )
                 const category = m.category && m.category !== 'reasoning' ? m.category : (hasReasoning ? null : 'general')
+                const categoryLabel = category === 'general' ? t('models.caps_general') : (category === 'coding' ? t('models.caps_coding') : category)
                 const hasVision = Boolean(m.input?.includes('image') || m.input?.includes('vision'))
                 return React.createElement(
                   React.Fragment,
                   null,
-                  category ? React.createElement('span', { className: 'cb-badge' }, category) : null,
+                  category ? React.createElement('span', { className: 'cb-badge' }, categoryLabel) : null,
                   hasVision
-                    ? React.createElement('span', { className: 'cb-badge', style: { marginLeft: category ? '4px' : '0' } }, 'Vision')
+                    ? React.createElement('span', { className: 'cb-badge', style: { marginLeft: category ? '4px' : '0' } }, t('models.caps_vision'))
                     : null,
                   hasReasoning
                     ? React.createElement(
                         React.Fragment,
                         null,
-                        React.createElement('span', { className: 'cb-badge cb-badge-ok', style: { marginLeft: (category || hasVision) ? '4px' : '0' }, title: t('models.reasoning_tooltip') }, '🧠 Reasoning'),
+                        React.createElement('span', { className: 'cb-badge cb-badge-ok', style: { marginLeft: (category || hasVision) ? '4px' : '0' }, title: t('models.reasoning_tooltip') }, t('models.reasoning_tag')),
                         React.createElement(
                           'select',
                           {
@@ -1579,10 +1671,10 @@ function ModelsSection({
                             },
                           },
                           React.createElement('option', { value: '' }, t('models.effort_auto')),
-                          React.createElement('option', { value: 'low' }, 'Low'),
-                          React.createElement('option', { value: 'medium' }, 'Medium'),
-                          React.createElement('option', { value: 'high' }, 'High'),
-                          React.createElement('option', { value: 'max' }, 'Max')
+                          React.createElement('option', { value: 'low' }, t('models.effort_low')),
+                          React.createElement('option', { value: 'medium' }, t('models.effort_medium')),
+                          React.createElement('option', { value: 'high' }, t('models.effort_high')),
+                          React.createElement('option', { value: 'max' }, t('models.effort_max'))
                         )
                       )
                     : null
@@ -1785,27 +1877,17 @@ function DiagSection({ keyPresent, isRegistered, busy, smokeResult, handleSmoke,
       ? React.createElement(
           'div',
           { className: 'cb-preview' },
-          `✅ Latency: ${smokeResult.latencyMs} ms | Model: ${smokeResult.model}
-Response: ${smokeResult.preview || '(empty)'}`
+          t('diag.smoke_result', {
+            latency: smokeResult.latencyMs,
+            model: smokeResult.model,
+            preview: smokeResult.preview || t('diag.empty'),
+          })
         )
       : null
   )
 }
 
 // --- src/client/settings-page.js ---
-function useConfigFormsSnapshot(ctx) {
-  const scope = React.useMemo(() => {
-    try { return readConfigForms(ctx)?.get?.(NS) || undefined } catch { return undefined }
-  }, [ctx])
-  const subscribe = React.useMemo(() => (cb) => {
-    try { return scope?.subscribe ? (scope.subscribe(cb) || (() => {})) : () => {} } catch { return () => {} }
-  }, [scope])
-  const getSnapshot = React.useCallback(() => {
-    try { return scope?.getSnapshot?.() || SNAPSHOT_READY } catch { return SNAPSHOT_READY }
-  }, [scope])
-  return React.useSyncExternalStore(subscribe, getSnapshot, () => SNAPSHOT_READY)?.status || 'loading'
-}
-
 function SettingsPage(props) {
   const ctx = props?.ctx
   const t = props?.t || makeT(en, en)
@@ -1819,8 +1901,9 @@ function SettingsPage(props) {
   const [smokeResult, setSmokeResult] = React.useState(null)
 
   const [updateState, setUpdateState] = React.useState({
-    checking: false, updating: false, currentVersion: '', latestVersion: '',
-    updateAvailable: false, canAutoUpdate: true, error: '', notice: '',
+    status: 'idle', checking: false, updating: false, currentVersion: '', latestVersion: '',
+    updateAvailable: false, canAutoUpdate: true, latestCheckFailed: false, lastCheckedAt: null,
+    error: '', notice: '',
   })
 
   const [apiKeyInput, setApiKeyInput] = React.useState('')
@@ -1847,23 +1930,45 @@ function SettingsPage(props) {
   }, [load])
 
   const checkUpdate = React.useCallback(async () => {
-    setUpdateState((s) => ({ ...s, checking: true, error: '' }))
+    setUpdateState((s) => ({ ...s, checking: true, status: 'checking', error: '' }))
     try {
       const res = await fetch(`${ROUTE_PREFIX}/update`)
       if (!res.ok) throw new Error(`HTTP ${res.status}`)
       const data = await res.json().catch(() => ({}))
+      if (data.latestCheckFailed) {
+        setUpdateState((s) => ({
+          ...s,
+          checking: false,
+          status: 'error',
+          latestCheckFailed: true,
+          currentVersion: data.currentVersion || s.currentVersion,
+          error: t('update.check_failed'),
+        }))
+        return
+      }
+      const isAvailable = Boolean(data.updateAvailable)
       setUpdateState((s) => ({
         ...s,
         checking: false,
+        status: isAvailable ? 'available' : 'current',
         currentVersion: data.currentVersion || s.currentVersion,
         latestVersion: data.latestVersion || '',
-        updateAvailable: !!data.updateAvailable,
+        updateAvailable: isAvailable,
+        latestCheckFailed: false,
+        lastCheckedAt: Date.now(),
         canAutoUpdate: data.canAutoUpdate !== false,
+        error: '',
+      }))
+    } catch (err) {
+      setUpdateState((s) => ({
+        ...s,
+        checking: false,
+        status: 'error',
+        latestCheckFailed: true,
+        error: String(err?.message || err || t('update.check_failed')),
       }))
-    } catch (_) {
-      setUpdateState((s) => ({ ...s, checking: false }))
     }
-  }, [])
+  }, [t])
 
   React.useEffect(() => { checkUpdate() }, [checkUpdate])
 
@@ -1881,13 +1986,20 @@ function SettingsPage(props) {
       setUpdateState((s) => ({
         ...s,
         updating: false,
+        status: 'current',
         updateAvailable: false,
         currentVersion: newVer,
+        lastCheckedAt: Date.now(),
         notice: t('update.done', { version: newVer }),
       }))
       setTimeout(() => checkUpdate(), 2000)
     } catch (err) {
-      setUpdateState((s) => ({ ...s, updating: false, error: t('update.failed', { error: String(err.message || err) }) }))
+      setUpdateState((s) => ({
+        ...s,
+        updating: false,
+        status: s.updateAvailable ? 'available' : 'error',
+        error: t('update.failed', { error: String(err?.message || err) }),
+      }))
     }
   }
 
@@ -1909,8 +2021,7 @@ function SettingsPage(props) {
     if (!keyVal) { setErr(t('key.empty_err')); return }
     await performAction('save-key', async () => {
       const res = await fetch(`${ROUTE_PREFIX}/save-key`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ apiKey: keyVal, apiKeyEnv: draft?.apiKeyEnv }),
       })
       const data = await res.json().catch(() => ({}))
@@ -1934,8 +2045,7 @@ function SettingsPage(props) {
   async function handleUpdateModelContext(payload) {
     await performAction('update-context', async () => {
       const res = await fetch(`${ROUTE_PREFIX}/models/context`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(payload),
       })
       const data = await res.json().catch(() => ({}))
@@ -2004,8 +2114,7 @@ function SettingsPage(props) {
       setVerifyStatus({ state: 'verifying', email: '', plan: '', error: '' })
       try {
         const res = await fetch(`${ROUTE_PREFIX}/key/verify`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ key: raw }),
         })
         const data = await res.json().catch(() => ({}))
@@ -2030,8 +2139,7 @@ function SettingsPage(props) {
   async function handlePinAccount(accountEnv) {
     await performAction('pin-account', async () => {
       const res = await fetch(`${ROUTE_PREFIX}/accounts/active`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ account: accountEnv }),
       })
       const data = await res.json().catch(() => ({}))
@@ -2043,8 +2151,7 @@ function SettingsPage(props) {
   async function handleAddAccount({ label, apiKeyEnv, apiKey }) {
     await performAction('add-account', async () => {
       const res = await fetch(`${ROUTE_PREFIX}/accounts`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ label, apiKeyEnv, apiKey }),
       })
       const data = await res.json().catch(() => ({}))
@@ -2057,8 +2164,7 @@ function SettingsPage(props) {
   async function handleDeleteAccount(accountEnv, deleteSecret = true) {
     await performAction('delete-account', async () => {
       const res = await fetch(`${ROUTE_PREFIX}/accounts/delete`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ apiKeyEnv: accountEnv, deleteSecret }),
       })
       const data = await res.json().catch(() => ({}))
@@ -2071,8 +2177,7 @@ function SettingsPage(props) {
     setDraft((d) => ({ ...(d || {}), ...(patch || {}) }))
     await performAction('patch-config', async () => {
       const res = await fetch(`${ROUTE_PREFIX}/config`, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
+        method: 'PUT', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ config: patch }),
       })
       const data = await res.json().catch(() => ({}))
@@ -2136,15 +2241,10 @@ function SettingsPage(props) {
   function handleSetModelsFilter(type) {
     const all = status?.availableModels || []
     let allowed = new Set()
-    if (type === 'all') {
-      allowed = new Set(all.map((m) => m.id))
-    } else if (type === 'vision') {
-      allowed = new Set(all.filter((m) => m.input?.includes('image') || m.input?.includes('vision')).map((m) => m.id))
-    } else if (type === 'coding') {
-      allowed = new Set(all.filter((m) => m.category === 'coding').map((m) => m.id))
-    } else if (type === 'recommended') {
-      allowed = new Set(all.filter((m) => m.recommended).map((m) => m.id))
-    }
+    if (type === 'all') allowed = new Set(all.map((m) => m.id))
+    else if (type === 'vision') allowed = new Set(all.filter((m) => m.input?.includes('image') || m.input?.includes('vision')).map((m) => m.id))
+    else if (type === 'coding') allowed = new Set(all.filter((m) => m.category === 'coding').map((m) => m.id))
+    else if (type === 'recommended') allowed = new Set(all.filter((m) => m.recommended).map((m) => m.id))
 
     const curr = draft?.disabledModels || []
     const nextDisabled = all.map((m) => m.id).filter((id) => !allowed.has(id))
@@ -2205,7 +2305,7 @@ function SettingsPage(props) {
     ),
 
     // In-app Update Bar
-    React.createElement(UpdateBanner, { updateState, handleTriggerUpdate, t }),
+    React.createElement(UpdateBanner, { updateState, handleTriggerUpdate, handleCheckUpdate: checkUpdate, t }),
 
     // Settings host status warning
     snapshotStatus === 'unavailable'
@@ -2338,7 +2438,7 @@ function PluginCard(props) {
           { style: { marginTop: '16px' } },
           React.createElement(
             ErrorBoundary,
-            null,
+            { t },
             React.createElement(SettingsPage, { ...props, ctx: props && props.ctx })
           )
         )
@@ -2423,7 +2523,7 @@ function apply(ctx) {
         locale: NS,
         inject: () => ({ ctx }),
       },
-      (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
+      (props) => React.createElement(ErrorBoundary, { t: props && props.t }, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
     )
   )
 
@@ -2440,7 +2540,7 @@ function apply(ctx) {
           locale: NS,
           inject: () => ({ ctx }),
         },
-        (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
+        (props) => React.createElement(ErrorBoundary, { t: props && props.t }, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
       )
     )
   }
@@ -2453,7 +2553,7 @@ function apply(ctx) {
         locale: NS,
         inject: () => ({ ctx }),
       },
-      (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
+      (props) => React.createElement(ErrorBoundary, { t: props && props.t }, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
     )
   )
 }

package/lib/provider-sync.js

@@ -123,12 +123,16 @@ export async function buildStatus(ctx, cfg) {
       if (fiveHour.percentUsed >= 95) {
         quotaWarning = {
           level: 'exhausted',
+          code: 'quota.exhausted_5h',
+          params: { percentUsed: fiveHour.percentUsed },
           message: `5-hour rolling limit is almost exhausted (${fiveHour.percentUsed}%). New requests may be rejected until quota reset.`,
           resetsAt: fiveHour.resetsAt,
         }
       } else if (fiveHour.percentUsed >= 90) {
         quotaWarning = {
           level: 'warning',
+          code: 'quota.warning_5h',
+          params: { percentUsed: fiveHour.percentUsed },
           message: `Low quota warning: ${fiveHour.percentUsed}% of 5-hour limit consumed (<10% remaining).`,
           resetsAt: fiveHour.resetsAt,
         }
@@ -136,17 +140,23 @@ export async function buildStatus(ctx, cfg) {
     }
 
     if (!quotaWarning && weekly && typeof weekly.percentUsed === 'number' && weekly.percentUsed >= 90) {
+      const remainingPercent = weekly.remainingPercent ?? (100 - weekly.percentUsed)
       quotaWarning = {
         level: weekly.percentUsed >= 99 ? 'exhausted' : 'warning',
-        message: `Low weekly quota warning: ${weekly.percentUsed}% consumed (${weekly.remainingPercent ?? (100 - weekly.percentUsed)}% remaining).`,
+        code: 'quota.warning_weekly',
+        params: { percentUsed: weekly.percentUsed, remainingPercent },
+        message: `Low weekly quota warning: ${weekly.percentUsed}% consumed (${remainingPercent}% remaining).`,
         resetsAt: weekly.resetsAt,
       }
     }
 
     if (!quotaWarning && monthly && typeof monthly.percentUsed === 'number' && monthly.percentUsed >= 90) {
+      const remainingPercent = monthly.remainingPercent ?? (100 - monthly.percentUsed)
       quotaWarning = {
         level: monthly.percentUsed >= 99 ? 'exhausted' : 'warning',
-        message: `Low monthly quota warning: ${monthly.percentUsed}% consumed (${monthly.remainingPercent ?? (100 - monthly.percentUsed)}% remaining).`,
+        code: 'quota.warning_monthly',
+        params: { percentUsed: monthly.percentUsed, remainingPercent },
+        message: `Low monthly quota warning: ${monthly.percentUsed}% consumed (${remainingPercent}% remaining).`,
         resetsAt: monthly.resetsAt,
       }
     }

package/lib/updater.js

@@ -219,10 +219,32 @@ export async function checkUpdateStatus(options, target = detectRuntime()) {
   }
 }
 
-async function installExact(target, packageSpec, options) {
+export function cleanStaleLock(profileDir) {
+  if (!profileDir) return false
+  const lockFile = resolve(profileDir, 'package.json.lock')
+  if (existsSync(lockFile)) {
+    try {
+      const pid = parseInt(readFileSync(lockFile, 'utf8').trim(), 10)
+      if (!isPidAlive(pid)) {
+        unlinkSync(lockFile)
+        return true
+      }
+    } catch (err) {
+      /* best-effort stale lock unlink */
+    }
+  }
+  return false
+}
+
+export async function installExact(target, packageSpec, options = {}) {
   if (target.cliEntry === undefined) throw new Error('Automatic update is unavailable in this runtime.')
+  const timeoutMs = typeof options.timeoutMs === 'number' ? options.timeoutMs : UPDATE_TIMEOUT_MS
+  const sigtermGraceMs = typeof options.sigtermGraceMs === 'number' ? options.sigtermGraceMs : 500
+  const sigkillGraceMs = typeof options.sigkillGraceMs === 'number' ? options.sigkillGraceMs : 500
+  const spawnFn = typeof options.spawn === 'function' ? options.spawn : spawn
+
   await new Promise((resolvePromise, reject) => {
-    const child = spawn(process.execPath, [
+    const child = spawnFn(process.execPath, [
       target.cliEntry, 'plugin', '--profile', target.profileName, 'add',
       packageSpec,
       `--registry=${options.registry || 'https://registry.npmjs.org/'}`,
@@ -235,40 +257,71 @@ async function installExact(target, packageSpec, options) {
     let detail = ''
     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('SIGTERM')
-      setTimeout(() => {
-        if (!child.killed) {
+
+    let exited = false
+    let isTimedOut = false
+    let sigtermTimer = null
+    let sigkillTimer = null
+
+    function cleanupTimers() {
+      clearTimeout(mainTimer)
+      if (sigtermTimer) clearTimeout(sigtermTimer)
+      if (sigkillTimer) clearTimeout(sigkillTimer)
+    }
+
+    function onProcessExit(code, signal) {
+      if (exited) return
+      exited = true
+      cleanupTimers()
+
+      if (isTimedOut) {
+        cleanStaleLock(target.profileDir)
+        reject(new Error('Update timed out.'))
+      } else if (code === 0) {
+        resolvePromise()
+      } else {
+        reject(new Error(detail.trim() || `Update exited with code ${String(code)}.`))
+      }
+    }
+
+    child.once('error', (error) => {
+      cleanupTimers()
+      reject(error)
+    })
+
+    child.once('exit', onProcessExit)
+    child.once('close', onProcessExit)
+
+    const mainTimer = setTimeout(() => {
+      isTimedOut = true
+      // Step 1: Send SIGTERM
+      try {
+        child.kill('SIGTERM')
+      } catch (err) {
+        /* ignore if process already terminated */
+      }
+
+      // Step 2: Wait for grace period, if process has not exited escalate to SIGKILL (#172)
+      sigtermTimer = setTimeout(() => {
+        const hasExited = exited || (child.exitCode !== null && child.exitCode !== undefined) || (child.signalCode !== null && child.signalCode !== undefined)
+        if (!hasExited) {
           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 */
-              }
+
+          // Step 3: Hard deadline for exit notification
+          sigkillTimer = setTimeout(() => {
+            if (!exited) {
+              exited = true
+              cleanStaleLock(target.profileDir)
+              reject(new Error('Update timed out.'))
             }
-          }
-        }, 100)
-      }, 500)
-      reject(new Error('Update timed out.'))
-    }, UPDATE_TIMEOUT_MS)
-    child.once('error', (error) => { clearTimeout(timer); reject(error) })
-    child.once('exit', (code) => {
-      clearTimeout(timer)
-      if (code === 0) resolvePromise()
-      else reject(new Error(detail.trim() || `Update exited with code ${String(code)}.`))
-    })
+          }, sigkillGraceMs)
+        }
+      }, sigtermGraceMs)
+    }, timeoutMs)
   })
 }
 

package/package.json

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