@goodandready/dsh-clinebot 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.6.3] - 2026-10-21
+
+### Added
+- **Quota forecast**: each 5-hour, weekly and monthly quota row now shows an estimated burn-down (`~2h 15m left`, `holds until reset`, `no usage yet`) based on the current pace and reset time. Forecasts appear in the sidebar and the center-column panel.
+- **Budget guard**: optional `dailyBudgetUsd` and `monthlyBudgetUsd` limits (0 disables). The adapter rejects new ClineBot requests with `BUDGET_EXCEEDED` once the local estimated spend for the UTC day/month reaches the limit; both fields are available in Settings → ClineBot → Advanced and the TUI.
+- Budget fields are wired through `publicConfig`, and the budget guard is covered by unit/integration tests.
+
+## [0.6.2] - 2026-10-21
+
+### Removed
+- **Legacy transport removed**: `transport: "pi-ai"`, `proxyMode`, `lib/proxy-server.js`, `lib/proxy-token.js`, `lib/routes/proxy.js`, the `llm/stream` failover hook and `/register` / `/unregister` routes are gone. ClineBot is adapter-only on `ctx.llm`.
+- **Legacy settings surfaces removed**: the transport selector, proxy diagnostics and proxy-mode toggle no longer appear in Settings or the TUI. A one-time cleanup still removes an old `llm-pi-ai.providers.clinebot` entry for users upgrading from 0.6.1.
+- **Legacy tests removed**; the adapter/session-router paths remain covered. Final bundle: 248.9 KB.
+
 ## [0.6.1] - 2026-10-21
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
 
 <h3>Native ClineBot / ClinePass Provider Companion for DeepSeek Harness</h3>
 
-<p><b>0.6.0</b> moves chat onto a native <code>ctx.llm</code> adapter. Requires DSH <code>0.2.1-rc.2</code>. The legacy <code>llm-pi-ai</code> + loopback-proxy path remains available behind <code>transport: "pi-ai"</code> for one release.</p>
+<p><b>0.6.3</b> adds quota burn-down forecasts and optional daily/monthly spend guards on top of the adapter-only line. Chat runs on the native <code>ctx.llm</code> adapter and requires DSH <code>0.2.1-rc.2</code>; the legacy <code>llm-pi-ai</code>, loopback proxy and <code>llm/stream</code> path are removed.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -118,7 +118,7 @@ graph LR
 * **`lib/adapter.js`**:
   Registers the `ClineBotAdapter` directly on `ctx.llm`: streaming, model catalogue, reasoning effort, pre-first-token account failover, retry policy, usage accounting and provider metadata.
 * **`lib/transport/cline-transport.js`**:
-  OpenAI-compatible SSE transport with connect/idle timeouts, abort handling and upstream error classification. The legacy proxy imports the same parser.
+  OpenAI-compatible SSE transport with connect/idle timeouts, abort handling and upstream error classification.
 * **`lib/models.js`**:
   Dynamic subscription catalogue, curated fallback properties, reasoning efforts, custom models and plan parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
 * **`lib/model-prices.js`**:
@@ -128,9 +128,9 @@ graph LR
 * **`lib/account-pool.js` / `lib/session-router.js`**:
   Credential discovery, usage-aware least-used and round-robin rotation, sticky sessions and cooldown recovery.
 * **`lib/cline-client.js`**:
-  `fetchUsageLimits`, credential save, smoke test, model cache and the legacy `llm-pi-ai` provider builder used only by `transport: "pi-ai"`.
+  `fetchUsageLimits`, credential save, smoke test and the model catalogue cache.
 * **`lib/index.js`**:
-  Cordis lifecycle: adapter registration, optional HTTP routes, quota warnings, `/cline` command, migration of the legacy provider and TUI section registration.
+  Cordis lifecycle: adapter registration, optional HTTP routes, quota warnings, `/cline` command, one-time cleanup of the old provider entry and TUI section registration.
 * **`lib/tui-settings.js`**:
   `dsh-TUI` section for key, base URL, model filters, active account, context window and output cap.
 * **`lib/client.js`**:
@@ -144,7 +144,7 @@ graph LR
 dsh plugin --profile web add @goodandready/dsh-clinebot
 ```
 
-Requires **DSH `0.2.1-rc.2`** and Node 22+. New installs use `transport: "adapter"` and register directly with `ctx.llm`. Set `transport: "pi-ai"` only if you still need the legacy `llm-pi-ai` provider and loopback proxy for one release.
+Requires **DSH `0.2.1-rc.2`** and Node 22+. ClineBot registers directly with `ctx.llm`; there is no transport switch or loopback proxy.
 
 Restart your DeepSeek Harness instance and refresh the browser.
 
@@ -191,13 +191,14 @@ dsh-clinebot:
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
   defaultModel: your-default-model
-  proxyMode: true
   disabledModels: []
   customModels: []
   modelReasoningDefaults:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  dailyBudgetUsd: 0
+  monthlyBudgetUsd: 0
   timeoutMs: 30000
   smokeTimeoutMs: 60000
   streamIdleTimeoutMs: 60000
@@ -218,8 +219,9 @@ dsh-clinebot:
 | `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 |
-| `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 |
+| `dailyBudgetUsd` | `number` | `0` | Optional estimated daily spend guard; 0 disables it |
+| `monthlyBudgetUsd` | `number` | `0` | Optional estimated monthly spend guard; 0 disables it |
 | `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` | `15000` | HTTP probe timeout in milliseconds |
@@ -232,7 +234,7 @@ dsh-clinebot:
 
 ## 🌐 HTTP API Endpoints
 
-All endpoints are registered under `/dsh-clinebot/*` and protected against untrusted cross-site origins (same-origin and loopback allowed). Control endpoints enforce a 256 KiB request payload limit; the loopback proxy endpoint supports up to 64 MiB payloads (`MAX_PROXY_BODY_BYTES`):
+All endpoints are registered under `/dsh-clinebot/*` and protected against untrusted cross-site origins (same-origin and loopback allowed). Control endpoints enforce a 256 KiB request payload limit:
 
 ### Management & Control Endpoints (Max 256 KiB)
 * `GET /dsh-clinebot/status` — Live status report including provider health, active credential, quota, and session metrics.
@@ -252,12 +254,6 @@ All endpoints are registered under `/dsh-clinebot/*` and protected against untru
 * `GET /dsh-clinebot/update/status` — Query available GitHub releases and plugin updates.
 * `POST /dsh-clinebot/update/apply` — Apply version upgrade with process-group cleanup and lockfile sync.
 
-### OpenAI-Compatible Loopback Proxy (Max 64 MiB)
-* `POST /dsh-clinebot/v1/chat/completions` — Transparent local proxy supporting streaming SSE and non-streaming responses, Bearer token authentication, sticky session affinity with least-used quota allocation, body read watchdog (`streamIdleTimeoutMs`), and automatic 429 failover.
-* `GET /dsh-clinebot/v1/models` — OpenAI-compatible catalog listing all active plan and custom models.
-
-> **DSH Desktop 2.x & Headless Environments**: The loopback proxy binds an isolated loopback HTTP server on `127.0.0.1` (ephemeral port), completely bypassing `DesktopWebServer` renderer fences (`x-dsh-desktop-renderer`). Automated fence detection (`detectHostWebServerFence`) falls back to direct upstream connection if the loopback server is restricted, and proxy mode can be directly toggled via the Diagnostics settings card.
-
 ---
 
 ## Visual verification

package/README.ru.md

@@ -4,7 +4,7 @@
 
 <h3>Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness</h3>
 
-<p><b>0.6.0</b> переводит чат на нативный адаптер <code>ctx.llm</code>. Требуется DSH <code>0.2.1-rc.2</code>. Старый путь <code>llm-pi-ai</code> + loopback-прокси остаётся за флагом <code>transport: "pi-ai"</code> на один релиз.</p>
+<p><b>0.6.3</b> добавляет прогноз расхода квоты и опциональные дневной/месячный лимиты трат. Чат работает через нативный адаптер <code>ctx.llm</code>, требуется DSH <code>0.2.1-rc.2</code>; старые <code>llm-pi-ai</code>, loopback-прокси и <code>llm/stream</code> удалены.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -84,7 +84,6 @@ graph LR
 
     subgraph DSHCore [Сервисы DSH]
         Credentials["Сервис credentials (~/.dsh/.credentials.yaml)"]
-        PiAi["Настройки: llm-pi-ai.providers.clinebot"]
     end
 
     subgraph Upstream [Сервер Cline]
@@ -99,7 +98,6 @@ graph LR
     HttpEndpoints --> Credentials
     HttpEndpoints --> ClientCore
     ClientCore --> ModelCatalog
-    HttpEndpoints -->|Атомарная мутация| PiAi
     ClientCore -->|Чат| ClinePass
     ClientCore -->|Квоты| ClineQuota
     ClientCore -->|Тарифный план| ClinePlan
@@ -115,7 +113,6 @@ graph LR
   * `sessionStats` / `recordSessionRequest`: счетчики сессии (запросы, токены, задержка, время).
   * `saveCredentialKey`: атомарная запись ключей в `~/.dsh/.credentials.yaml`.
   * `smokeChat`: замер задержки и тестовый пинг с фиксацией статистики.
-  * `buildPiAiProvider`: генерация конфигурации провайдера для `llm-pi-ai` (`api: 'openai-completions'`).
 * **`lib/index.js`**: сервис Cordis, регистрация системных маршрутов (включая `/dsh-clinebot/models/sync`), расчет порогов предупреждения квоты и слэш-команды `/cline`.
 * **`lib/client.js`**: страница конфигурации строки плагина (`plugins.row.config`) с предупреждениями, статистикой сессии, синхронизацией моделей и запасной карточкой (`settings.plugin.item`). Пункта `settings.section` в боковом меню нет.
 
@@ -163,13 +160,14 @@ dsh-clinebot:
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
   defaultModel: your-default-model
-  proxyMode: true
   disabledModels: []
   customModels: []
   modelReasoningDefaults:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  dailyBudgetUsd: 0
+  monthlyBudgetUsd: 0
   timeoutMs: 30000
   smokeTimeoutMs: 60000
   streamIdleTimeoutMs: 60000
@@ -190,8 +188,9 @@ dsh-clinebot:
 | `customModels` | `array` | `[]` | Пользовательские модели шлюза (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
 | `modelReasoningDefaults` | `object` | `{}` | Значения thinking effort по умолчанию для моделей (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | Пользовательские переопределения размера контекста и лимита токенов |
-| `proxyMode` | `boolean` | `true` | Включение локального прозрачного loopback-прокси с сессионным роутингом и failover |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Путь к файлу персистентной аналитики использования токенов |
+| `dailyBudgetUsd` | `number` | `0` | Опциональный дневной лимит оценочных трат; 0 отключает |
+| `monthlyBudgetUsd` | `number` | `0` | Опциональный месячный лимит оценочных трат; 0 отключает |
 | `accounts` | `array` | `[]` | Дополнительные аккаунты для ротации квоты и failover (`[{ label, apiKeyEnv }]`) |
 | `activeAccount` | `string` | `""` | Принудительно закреплённый аккаунт (пусто для автоматического выбора least-used) |
 | `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) |
@@ -204,7 +203,7 @@ dsh-clinebot:
 
 ## 🌐 Маршруты HTTP API
 
-Все маршруты регистрируются с префиксом `/dsh-clinebot/*` и защищены от межсайтовых запросов (разрешены same-origin и loopback). Управляющие эндпоинты ограничены лимитом 256 КиБ; прокси-эндпоинт поддерживает до 64 МиБ полезной нагрузки (`MAX_PROXY_BODY_BYTES`):
+Все маршруты регистрируются с префиксом `/dsh-clinebot/*` и защищены от межсайтовых запросов (разрешены same-origin и loopback). Управляющие эндпоинты ограничены лимитом 256 КиБ:
 
 ### Управляющие эндпоинты (макс. 256 КиБ)
 * `GET /dsh-clinebot/status` — Текущее состояние провайдера, активный аккаунт, квоты и статистика сессий.
@@ -224,12 +223,6 @@ dsh-clinebot:
 * `GET /dsh-clinebot/update/status` — Проверка наличия обновлений плагина.
 * `POST /dsh-clinebot/update/apply` — Обновление плагина с корректным завершением групп процессов и блокировками профиля.
 
-### OpenAI-совместимый loopback-прокси (макс. 64 МиБ)
-* `POST /dsh-clinebot/v1/chat/completions` — Прозрачный локальный прокси с поддержкой SSE и нестриминговых ответов, Bearer-аутентификацией, сессионной липкостью и least-used распределением квот, контролем дедлайнов (`streamIdleTimeoutMs`) и автоматическим 429 failover.
-* `GET /dsh-clinebot/v1/models` — Каталог моделей в стандарте OpenAI API.
-
-> **DSH Desktop 2.x и автономные окружения**: Прокси поднимает изолированный выделенный HTTP-сервер на `127.0.0.1` (эфемеридный порт), полностью обходя сетевые экраны `DesktopWebServer` (`x-dsh-desktop-renderer`). Встроенный детектор защитных экранов (`detectHostWebServerFence`) автоматически переключает провайдер на прямое соединение с upstream при ограничении loopback-порта, а режим прокси можно переключать напрямую в карточке «Диагностика» в UI.
-
 ---
 
 ## 🧪 Тестирование

package/README.zh.md

@@ -4,7 +4,7 @@
 
 <h3>适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件</h3>
 
-<p><b>0.6.0</b> 将聊天迁移到原生 <code>ctx.llm</code> 适配器。需要 DSH <code>0.2.1-rc.2</code>。旧的 <code>llm-pi-ai</code> + 回环代理路径保留一个版本，通过 <code>transport: "pi-ai"</code> 启用。</p>
+<p><b>0.6.3</b> 添加配额消耗预测和可选的每日/每月花费上限。聊天使用原生 <code>ctx.llm</code> 适配器，需要 DSH <code>0.2.1-rc.2</code>；旧的 <code>llm-pi-ai</code>、回环代理和 <code>llm/stream</code> 已删除。</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -84,7 +84,6 @@ graph LR
 
     subgraph DSHCore [DSH 核心系统服务]
         Credentials["凭据存储服务 (~/.dsh/.credentials.yaml)"]
-        PiAi["模型注册: llm-pi-ai.providers.clinebot"]
     end
 
     subgraph Upstream [Cline 官方云端]
@@ -99,7 +98,6 @@ graph LR
     HttpEndpoints --> Credentials
     HttpEndpoints --> ClientCore
     ClientCore --> ModelCatalog
-    HttpEndpoints -->|原子级写入| PiAi
     ClientCore -->|模型对话| ClinePass
     ClientCore -->|额度查询| ClineQuota
     ClientCore -->|套餐信息| ClinePlan
@@ -115,7 +113,6 @@ graph LR
   * `sessionStats` / `recordSessionRequest`：内存级会话度量记录器（请求次数、Token 估算、延迟、时间戳）。
   * `saveCredentialKey`：将密钥安全写入 `~/.dsh/.credentials.yaml`。
   * `smokeChat`：毫秒级网络探活与非流式延迟测试，并记录会话指标。
-  * `buildPiAiProvider`：构建 DSH `llm-pi-ai` 兼容的服务商定义 (`api: 'openai-completions'`)。
 * **`lib/index.js`**：Cordis 插件主生命周期服务，注册后端 REST API 路由（含 `/dsh-clinebot/models/sync`）、额度预警计算与 `/cline` 聊天斜杠指令。
 * **`lib/client.js`**：插件行配置页（`plugins.row.config`），含预警横幅、会话指标、一键模型同步，以及后备插件卡片（`settings.plugin.item`）。没有 `settings.section` 侧边栏项。
 
@@ -165,13 +162,14 @@ dsh-clinebot:
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
   defaultModel: your-default-model
-  proxyMode: true
   disabledModels: []
   customModels: []
   modelReasoningDefaults:
     your-reasoning-model: high
   modelContextOverrides: []
   statsPath: ~/.dsh/clinebot-stats.json
+  dailyBudgetUsd: 0
+  monthlyBudgetUsd: 0
   timeoutMs: 30000
   smokeTimeoutMs: 60000
   streamIdleTimeoutMs: 60000
@@ -192,8 +190,9 @@ dsh-clinebot:
 | `customModels` | `array` | `[]` | 用户自定义网关模型 (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
 | `modelReasoningDefaults` | `object` | `{}` | 各模型默认思考强度配置 (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | 用户自定义模型上下文窗口与最大 Token 数量覆盖 |
-| `proxyMode` | `boolean` | `true` | 启用透明本地环回代理以支持会话粘性路由与 429 自动故障转移 |
 | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | 本地持久化 Token 用量统计文件路径 |
+| `dailyBudgetUsd` | `number` | `0` | 可选的每日估算花费上限；0 表示关闭 |
+| `monthlyBudgetUsd` | `number` | `0` | 可选的每月估算花费上限；0 表示关闭 |
 | `accounts` | `array` | `[]` | 额外轮转账号池 (`[{ label, apiKeyEnv }]`) |
 | `activeAccount` | `string` | `""` | 手动指定的主账号（为空时自动按最低配额消耗优先路由） |
 | `timeoutMs` | `number` | `15000` | HTTP 请求探测超时时间（毫秒） |
@@ -206,7 +205,7 @@ dsh-clinebot:
 
 ## 🌐 HTTP API 接口说明
 
-所有接口挂载于 `/dsh-clinebot/*` 路径，并受到跨站请求防护（仅放行同源或环回请求）。管理接口限制请求体上限 256 KiB；环回推理代理接口支持最高 64 MiB 有效载荷 (`MAX_PROXY_BODY_BYTES`)：
+所有接口挂载于 `/dsh-clinebot/*` 路径，并受到跨站请求防护（仅放行同源或环回请求）。管理接口限制请求体上限 256 KiB：
 
 ### 管理与控制接口（上限 256 KiB）
 * `GET /dsh-clinebot/status` — 服务运行状态，包括健康探活、当前凭据名称、配额限制及会话统计。
@@ -226,12 +225,6 @@ dsh-clinebot:
 * `GET /dsh-clinebot/update/status` — 查询插件版本更新状态。
 * `POST /dsh-clinebot/update/apply` — 应用版本更新（支持进程树完全清理与锁文件保护）。
 
-### OpenAI 兼容环回代理接口（上限 64 MiB）
-* `POST /dsh-clinebot/v1/chat/completions` — 本地透明代理，支持 SSE 流式与完整响应、会话粘性路由、最低用量负载均衡、响应体超时防护 (`streamIdleTimeoutMs`) 以及 429 自动故障转移。
-* `GET /dsh-clinebot/v1/models` — 符合 OpenAI API 规范的模型列表。
-
-> **DSH Desktop 2.x 与无界面环境**：环回代理在 `127.0.0.1` 绑定独立的专用 HTTP 服务（临时端口），彻底绕过桌面端路由防护 (`DesktopWebServer` 的 `x-dsh-desktop-renderer` 限制）。内置防护检测机制 (`detectHostWebServerFence`) 在环回端口受限时自动回退为直连模式，用户亦可在设置页的“诊断”模块中直接切换代理模式。
-
 ---
 
 ## 🧪 测试

package/lib/adapter.js

@@ -12,7 +12,8 @@ import { getAllModels, findModel, formatModelDescription } from './models.js'
 import { resolveAccountPool } from './account-pool.js'
 import { resolveSessionAccount, markAccountCooldown } from './session-router.js'
 import { recordSessionRequest } from './telemetry.js'
-import { recordUsage } from './stats-storage.js'
+import { recordUsage, getBudgetSpend } from './stats-storage.js'
+import { budgetStatus, budgetErrorMessage } from './budget.js'
 import { estimateCost } from './model-prices.js'
 import { buildOpenAiPayload } from './adapter-messages.js'
 import { streamJsonCompletion, streamOpenAiChunks } from './adapter-stream.js'
@@ -244,6 +245,10 @@ export class ClineBotAdapter extends LlmAdapter {
     if (!pub.enabled) {
       throw new LlmError('ClineBot provider is disabled', 'PROVIDER_DISABLED')
     }
+    const budget = budgetStatus(pub, getBudgetSpend())
+    if (budget.blocked) {
+      throw new LlmError(budgetErrorMessage(budget), 'BUDGET_EXCEEDED')
+    }
 
     const signal = options.signal
     const sessionId = options.sessionId ? String(options.sessionId) : ''

package/lib/budget.js

@@ -0,0 +1,37 @@
+/**
+ * Estimated-spend budget guard.
+ *
+ * ClinePass does not expose a per-token invoice; spend comes from the local
+ * price table and is therefore explicit about being an estimate. A guard of 0
+ * disables the corresponding limit.
+ */
+
+/**
+ * @param {{ dailyBudgetUsd?: number, monthlyBudgetUsd?: number }} config
+ * @param {{ dayCost?: number, monthCost?: number }} spend
+ * @returns {{ blocked: boolean, scope: 'daily'|'monthly'|null, spent: number, limit: number }}
+ */
+export function budgetStatus(config, spend) {
+  const dailyLimit = Math.max(0, Number(config?.dailyBudgetUsd) || 0)
+  const monthlyLimit = Math.max(0, Number(config?.monthlyBudgetUsd) || 0)
+  const dayCost = Math.max(0, Number(spend?.dayCost) || 0)
+  const monthCost = Math.max(0, Number(spend?.monthCost) || 0)
+
+  if (dailyLimit > 0 && dayCost >= dailyLimit) {
+    return { blocked: true, scope: 'daily', spent: dayCost, limit: dailyLimit }
+  }
+  if (monthlyLimit > 0 && monthCost >= monthlyLimit) {
+    return { blocked: true, scope: 'monthly', spent: monthCost, limit: monthlyLimit }
+  }
+  return { blocked: false, scope: null, spent: 0, limit: 0 }
+}
+
+/**
+ * Human-readable error for an exhausted budget guard.
+ * @param {ReturnType<typeof budgetStatus>} status
+ */
+export function budgetErrorMessage(status) {
+  if (!status?.blocked) return ''
+  const label = status.scope === 'monthly' ? 'Monthly' : 'Daily'
+  return `${label} ClineBot budget reached (estimated $${status.spent.toFixed(4)} of $${status.limit.toFixed(2)}). Raise the limit in Settings -> ClineBot -> Advanced.`
+}