dsh-workbuddy-xdpool 1.7.6 → 1.7.8

package/CHANGELOG.md

@@ -4,6 +4,140 @@
 
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## 1.7.8 — 说清楚卡片在哪儿、以及我们支持到哪个版本
+
+> 这次没有功能问题，全在「声明」上：一处把你引到不存在的路径，一处让你以为装错了版本。
+
+### README 的入口路径是 0.1.x 时代的，0.2.0 上按它找不到
+
+README 一直写着「设置 → 插件 → DSH WorkBuddy XD Pool」。**0.2.0 起没有这条二层路径了。**
+
+实际位置是：**打开设置面板 → 顶部平级标签里的「XD Pool」**（排在 `通用设置 / 模型 / 内置插件 / Agent 预设` 后面）。开设置面板的方式是**侧边栏左下角的齿轮**，或快捷键 `Ctrl+Alt+,`。
+
+已把 README 三处改掉，并且**补上了开面板的方法**——只写「切到 XD Pool」而不说怎么开设置，等于没写。老路径保留一句「0.1.x 时代叫这个」，方便升级上来的人理解自己的习惯为什么突然不灵了。
+
+### `engines.dsh` 写着 `<0.2.0`，可它在 0.2.0 上跑得好好的
+
+这个声明的问题不在于"保守"，而在于**它会把人带偏**：任何人按 `engines` 做兼容判断，第一反应都是"这插件不支持 0.2.0"，然后往错误的方向排查。反馈里就有一位因此走了一大圈。
+
+现在放宽到 `<0.3.0`，并且**把三个 host peer 依赖（`dsh-llm` / `dsh-llm-pi-ai` / `dsh-settings`）一起对齐**——它们约束的是同一批宿主包，只改一个反而制造新的不一致。
+
+放宽不等于"什么都接受"：上界仍然卡在 `<0.3.0`，**没测过的大版本不该被默认声称支持**。
+
+### 导航图标匹配不上时，现在会说话
+
+`installNavIcon()` 靠选择器找设置面板里那一行。**找不到时它完全静默** —— 表现就是"图标没出来"，没有任何线索。这次排查里它不是故障点，但它是最贵的一环：**看起来什么都没发生**。
+
+现在连续匹配失败会 `console.warn` 一次，带上选择器、期望的标签、以及**当前导航里实际有什么**：
+
+```
+[dsh-workbuddy-xdpool] the settings nav row could not be found, so the icon was not applied.
+selector="[role=\"dialog\"] nav button" expectedLabel="XD Pool" rowsPresent=["通用设置","模型",...]
+This is cosmetic only — the card itself still works. Please report this line…
+```
+
+**不是每次都喊**：设置面板没打开时找不到是**正常的**（那一行压根不在 DOM 里），每次都喊只会让人学会忽略它。所以只在"面板开着、却连续 N 次找不到"时才报一次，且每轮只报一次。
+
+### 关于那份"0.2.0 删了 slots 服务"的报告
+
+反馈者**自己撤回了**那个结论，我更正一下：**不成立**。
+
+他后来实测到：`__DSH_BOOT__.entries` 含本插件、`importErrors` 为空、客户端 fiber 状态是 ACTIVE、卡片 DOM 完整渲染、`installNavIcon` 正常生效。而且**把 `dsh.client.inject` 改掉再测，行为完全一致** —— 所以那两个包的声明**不会阻断加载，不需要改**。
+
+他复盘出的两个方法论坑，我认为值得原样记下来，因为它们非常容易重犯：
+- 只用正则扫「谁 `provide("name")` 了服务」，漏掉别的声明写法，就宣布服务被删了 —— **典型的假阴性**；
+- 在**会话页**（设置面板没开）dump DOM 搜插件节点，0 命中当成故障证据 —— 而 `settings.section` **只在面板打开时才进 DOM**，0 命中是必然的。
+
+`slots` 和 `settings.section` 在 0.2.0 里都健在，渲染方是 `dsh-client-ui-settings-general` 的 `renderSlot("settings.section", …)`。
+
+### 验证
+
+- 类型检查全绿，测试 **332 项全绿**（+7）。
+- 新增 `tests/compatibility-declaration.test.ts`：`engines.dsh` 必须容纳 0.2.x、**上界仍要卡住没测过的大版本**、三个 host peer 与 `engines.dsh` 保持一致、README **不得再把老路径当指引**（但允许作为历史说明出现）、必须写出开设置面板的方法。
+- **反向验证**：把 `engines` 退回 `<0.2.0` → 2 项变红；把 README 退回老路径 → 1 项变红。
+- 本机核对宿主代码：`renderSlot("settings.section", { close }, { only: active })` 确为**平级渲染**，插件注册 `order: 440`（排最后），与反馈的实测描述一致。
+
+### 一点说明
+
+我本机是 DSH Desktop 2.0.15（内核 0.1.7-rc.2），**不是 0.2.0-rc.2**，所以我**没法在本地复现 0.2.0 的渲染行为**。本次改动依据的是反馈者提供的实测数据，外加我对本机宿主代码里 `renderSlot` 调用的核对。放宽 `engines` 这个结论我是采信的，但没有在 0.2.0 上亲手验过。
+
+## 1.7.7 — 别再让你为了一个「等一会儿」去重新登录
+
+> 报错说「API 密钥无效」，于是你跑去重新登录 —— 但密钥根本没问题，只是那个模型暂时限流了。
+
+### 问题一：限流被说成了「密钥无效」
+
+**你会看到**：国际版用 hy4 时，偶尔弹出「API 密钥无效」。你重新登录、换账号，都不一定管用。
+
+**为什么**：看日志就清楚了（时间连着三行）：
+
+```
+14:50:22  qingche526  rate-limited on hy4-preview-f  → cooling + rotating
+14:50:23  aosi526     rate-limited on hy4-preview-f  → cooling + rotating
+14:50:25  401: "no WorkBuddy credential found; sign in on the desktop app"
+```
+
+两个账号的 hy4-preview-f 都被限流**冷却**了（一小时），于是池子里暂时没有可用账号。可插件判断「有没有被限流」用的是**本次请求内**的临时记录 —— 上次请求造成的冷却，它看不见。于是它以为「一个账号都没有 → 你没登录」→ 报 **401**。
+
+DSH 把 401 显示成「API 密钥无效」。**你被派去修一个根本没坏的东西。**
+
+**怎么修的**：不再靠本次请求的临时记录猜，而是**直接问账号池「为什么现在没有可用账号」**，然后按真实原因报对应的错：
+
+| 真实情况 | 以前 | 现在 |
+|---|---|---|
+| 模型限流中 | 401 密钥无效 | **429 该模型限流中**（等一会儿即可）|
+| 账号全被关/移出 | 401 密钥无效 | **403 账号全部已关闭**（去卡片打开）|
+| 积分低于保留线 | 401 密钥无效 | **402 积分不足** |
+| 确实没登录 | 401 | 401（这个才是对的）|
+
+四种情况**需要完全相反的处理**，以前却都推给你「重新登录」。现在只有真的该重新登录时才这么说。
+
+### 问题二：上下文「压缩」把目标设得比原文还大
+
+日志里抓到的：
+
+```
+context overrun on deepseek-v4.1-flash (~791793 tokens); compacting to ~797952
+                                  ↑ 原文 79.1 万                    ↑ 目标 79.7 万
+```
+
+**压缩目标比要压缩的东西还大** —— 等于什么都没压，重试当然又超限。而日志看起来还挺像"我处理过了"。
+
+**为什么**：目标值是按**目录里写的窗口**算的（`deepseek-v4.1-flash` 标称 1M），取 80% → `797952`。但**标称 1M 是宣传值，不是真实生效上限** —— 否则它就不会被拒了。
+
+**怎么修的**：**正在超限的那个请求本身就是证据**。既然它太大了，目标就必须明显小于它。现在取「按窗口算」和「按原文一半」的较小值：
+
+```
+原文 791793 → 目标 395896      （真正压掉一半）
+```
+
+### 顺便：这类报错终于有线索了
+
+上游的 `model_param_invalid` 里 **`param` 字段是空的** —— 它只说「参数不符合要求」，不说是哪个参数。你之前贴的那条 11133 就是这样，等于没有线索。
+
+现在遇到 400 时，日志会记下**请求的形状**（顶层参数名、各角色的消息条数、工具数量、内容字符数）：
+
+```
+rejected the request as invalid (model deepseek-v4.1-flash) —
+keys=[max_tokens messages model reasoning_effort stream temperature tool_choice tools top_k top_p]
+messages=122 (system:1 user:61 assistant:30 tool:30) tools=77 contentChars=481233
+```
+
+**只有形状，没有内容**（对话是你的，不该进日志）。下次再遇到，日志里就能看出是哪个参数/哪个维度不对。
+
+### 我排查时的事
+
+我一开始想直接复现 11133，试了：采样参数（`top_k`/`repetition_penalty`/`temperature`/`top_p`）、推理档位（`minimal` 到 `max`，还试了无效档位）、各种消息形状（回放 `reasoning_content`、工具调用链）、消息数量（最多 362 条）、77 个工具 + 长会话、超长 prompt ——**国内版和国际版全部返回 200**。
+
+**我没能复现它**，所以没有针对 11133 写"修复"（那会是猜测）。改的都是**从日志里坐实的**问题：那两个是确凿的。这个 11133 加上刚加的形状日志，下次出现时就能定位了。
+
+### 验证
+
+- 类型检查全绿，测试 **325 项全绿**（+12）。
+- 新增 `tests/pool-availability.test.ts`（7 项）：池能正确区分「无人登录 / 模型限流 / 账号全关 / 积分保留 / 可用」、**限流时返回 429 且文案不含「sign in」**、真没登录时仍是 401、**不把另一个 region 的账号算进来**、过期冷却自动视为可用。
+- 新增 `tests/context-budget-budget.test.ts`（5 项）：**目录窗口远大于原文时目标必须更小**（用日志里那组真实数字）、窗口未知时减半、窗口小于原文时也不放大、目标不为零。
+- **反向验证**：把 429 分支禁用、退回原来的 401 → 测试变红。
+
 ## 1.7.6 — 一个读不出来的凭据文件，不再带走整个账号池
 
 > 你切了 4 个账号登录，界面显示 4 个；重启之后只剩 2 个 —— 不是账号没了，是它们被一个文件拖累了。

package/README.md

@@ -19,7 +19,7 @@
 
 ## 先看几张图
 
-**插件配置卡片（设置 → 插件 → DSH WorkBuddy XD Pool）**
+**插件配置卡片（设置 → 「XD Pool」一节）**
 
 ![WorkBuddy 池设置卡片：国内版 / 国际版切换栏、池健康状态、账号面板、积分包与合计、每账号每日签到、积分自动化面板、模型管理](assets/settings-card.png)
 
@@ -83,9 +83,13 @@
 
 ## 安装
 
-前置条件：装好 WorkBuddy 桌面 App 并登录（插件复用它存在本机的登录状态）。多账号 = 在桌面 App 里换着登几次，每次登录都会被自动吸进池里。已针对 DSH Desktop host `0.1.2` 适配。
+前置条件：装好 WorkBuddy 桌面 App 并登录（插件复用它存在本机的登录状态）。多账号 = 在桌面 App 里换着登几次，每次登录都会被自动吸进池里。
 
-> 兼容 host `0.1.1-rc.2` / `0.1.2` 系列：安装设置节时会按 host 能力自动选择 `settings.installSection`（0.1.2-rc.1+）或更早的自由函数写法。
+> 兼容 host `0.1.1-rc.2` 起的整个 0.1.x 系列，以及 `0.2.0-rc.2`。安装设置节时会按 host 能力自动选择 `settings.installSection`（0.1.2-rc.1+）或更早的自由函数写法；卡片在 0.2.0 上作为设置面板里一个**平级标签页**渲染。
+
+> **卡片在哪儿打开**：DSH 设置面板本身。开法是**侧边栏左下角的齿轮**，或者快捷键 `Ctrl+Alt+,`。
+> 面板顶部是平级标签：`通用设置 / 模型 / 内置插件 / Agent 预设 / XD Pool` —— 本插件就是最后那个 **XD Pool**。
+> （0.1.x 时代它叫「设置 → 插件 → DSH WorkBuddy XD Pool」，0.2.0 起改成了平级标签，按老路径找不到。）
 
 **方式一：从 npm 安装（推荐）**
 
@@ -129,7 +133,7 @@ pnpm typecheck:client   # 客户端类型检查
 
 > 注意：`pnpm install` 要用 pnpm 11（`npx pnpm@11`），必要时加 `--config.confirmModulesPurge=false --config.minimumReleaseAge=0`——pnpm 11 默认的 `minimumReleaseAge` 供应链年龄策略会拦下刚发布的 rc 包。
 
-装完以后：模型选择器里会出现 **WorkBuddy XD Pool** 分组；设置 → 插件 → **DSH WorkBuddy XD Pool** 能看池健康、各账号的令牌 / 积分 / 签到 / 冷却状态，还有「重新检测账号」「清除所有冷却」按钮和每个账号的签到按钮。
+装完以后：模型选择器里会出现 **WorkBuddy XD Pool** 分组；打开设置面板（左下角齿轮或 `Ctrl+Alt+,`）切到 **XD Pool** 一栏，能看池健康、各账号的令牌 / 积分 / 签到 / 冷却状态，还有「重新检测账号」「清除所有冷却」按钮和每个账号的签到按钮。
 
 Web / TUI profile 也能用（`--profile web` / `--profile dsh-tui`）。
 

package/lib/bin.js

@@ -2846,6 +2846,70 @@ var WorkBuddyAccountPool = class {
 			return true;
 		});
 	}
+	/**
+	* Why no account is available right now, for an accurate error.
+	*
+	* The pool can be empty for reasons that need OPPOSITE remedies: nobody is
+	* signed in (the user must sign in), every account is rate-limited (the user
+	* must wait, and retrying later works), or every account was switched off /
+	* ignored (the user must re-enable one). Reporting all of them as "no
+	* credential, sign in" sent users to re-authenticate over a temporary 429 —
+	* observed as an "API key invalid" panel for a model that was merely cooling.
+	*
+	* Counts are over the region's accounts, since a provider only ever sees its
+	* own gateway.
+	*/
+	unavailableReason(modelId, region) {
+		const now = Date.now();
+		const inRegion = this.accounts.filter((account) => region === void 0 || regionOf(account.credential.domain) === region);
+		if (inRegion.length === 0) return {
+			total: 0,
+			cooling: 0,
+			disabled: 0,
+			reason: "empty"
+		};
+		let cooling = 0;
+		let disabled = 0;
+		for (const account of inRegion) {
+			if (this.disabledIds.has(account.id)) {
+				disabled += 1;
+				continue;
+			}
+			const modelCooling = modelId !== void 0 && (account.modelCooldowns[modelId] ?? 0) > now;
+			if (account.cooldownUntilMs > now || modelCooling) {
+				cooling += 1;
+				continue;
+			}
+			const reserve = this.creditReserves.get(account.id);
+			if (reserve !== void 0 && reserve > 0) {
+				const balance = this.creditBalances.get(account.id);
+				if (balance !== void 0 && balance <= reserve) return {
+					total: inRegion.length,
+					cooling,
+					disabled,
+					reason: "reserve"
+				};
+			}
+		}
+		if (cooling > 0) return {
+			total: inRegion.length,
+			cooling,
+			disabled,
+			reason: "cooling"
+		};
+		if (disabled > 0) return {
+			total: inRegion.length,
+			cooling,
+			disabled,
+			reason: "disabled"
+		};
+		return {
+			total: inRegion.length,
+			cooling,
+			disabled,
+			reason: "none"
+		};
+	}
 	/** Round-robin: the legacy cursor walk, kept for the distribution that asks for it. */
 	pickRoundRobin(pool) {
 		const index = this.cursor % pool.length;

package/lib/client.js

@@ -2536,6 +2536,15 @@ window.__ModuleLoader__.load({
 		*/
 		const NAV_ROW_SELECTOR = "[role=\"dialog\"] nav button";
 		/**
+		* How many consecutive in-dialog passes may miss the nav row before the
+		* diagnostic fires.
+		*
+		* Above 1 because a single miss is routine — the shell can re-render between
+		* our mutation callback and the query. Small enough that a genuinely broken
+		* selector is reported within a frame or two of opening the settings panel.
+		*/
+		const NAV_ICON_MISS_THRESHOLD = 3;
+		/**
 		* Draw this page's own glyph in its Settings nav row.
 		*
 		* The `settings.section` contract carries no icon: the shell decides the glyph
@@ -2576,13 +2585,46 @@ window.__ModuleLoader__.load({
 				document.head.appendChild(tag);
 				let disposed = false;
 				let scheduled = false;
+				/**
+				* Consecutive passes that found no matching row.
+				*
+				* A miss is NORMAL most of the time: the settings dialog is closed, so its
+				* nav is not in the DOM at all, and the icon stays unapplied by design.
+				* Warning on the first miss would fire constantly and train everyone to
+				* ignore it.
+				*
+				* What is worth reporting is a PERSISTENT miss while the dialog IS open —
+				* that means the shell's nav markup changed and the selector no longer
+				* matches, which is exactly the failure that looks like "nothing happened"
+				* and cost hours to find. So the threshold is a burst of misses, and the
+				* warning is emitted once per burst rather than once per mutation.
+				*/
+				let missStreak = 0;
+				let warned = false;
 				const sync = () => {
 					scheduled = false;
 					if (disposed) return;
 					const wanted = String(resolveLabel() ?? "").trim();
 					if (wanted === "") return;
-					for (const row of document.querySelectorAll(NAV_ROW_SELECTOR)) if (String(row.textContent ?? "").trim() === wanted) row.setAttribute(NAV_ICON_MARKER, "");
-					else row.removeAttribute(NAV_ICON_MARKER);
+					let matched = 0;
+					for (const row of document.querySelectorAll(NAV_ROW_SELECTOR)) if (String(row.textContent ?? "").trim() === wanted) {
+						row.setAttribute(NAV_ICON_MARKER, "");
+						matched += 1;
+					} else row.removeAttribute(NAV_ICON_MARKER);
+					if (matched > 0) {
+						missStreak = 0;
+						warned = false;
+						return;
+					}
+					if (document.querySelector(NAV_ROW_SELECTOR) === null) {
+						missStreak = 0;
+						return;
+					}
+					missStreak += 1;
+					if (missStreak < NAV_ICON_MISS_THRESHOLD || warned) return;
+					warned = true;
+					const present = [...document.querySelectorAll(NAV_ROW_SELECTOR)].map((row) => String(row.textContent ?? "").trim()).filter((text) => text !== "");
+					console.warn(`[dsh-workbuddy-xdpool] the settings nav row could not be found, so the icon was not applied. selector=${JSON.stringify(NAV_ROW_SELECTOR)} expectedLabel=${JSON.stringify(wanted)} rowsPresent=${JSON.stringify(present)}. This is cosmetic only — the card itself still works. Please report this line so the selector can be updated.`);
 				};
 				const schedule = () => {
 					if (scheduled || disposed) return;

package/lib/index.d.ts

@@ -989,6 +989,25 @@ export declare class WorkBuddyAccountPool {
    * model, e.g. CLI diagnostics).
    */
   private available;
+  /**
+   * Why no account is available right now, for an accurate error.
+   *
+   * The pool can be empty for reasons that need OPPOSITE remedies: nobody is
+   * signed in (the user must sign in), every account is rate-limited (the user
+   * must wait, and retrying later works), or every account was switched off /
+   * ignored (the user must re-enable one). Reporting all of them as "no
+   * credential, sign in" sent users to re-authenticate over a temporary 429 —
+   * observed as an "API key invalid" panel for a model that was merely cooling.
+   *
+   * Counts are over the region's accounts, since a provider only ever sees its
+   * own gateway.
+   */
+  unavailableReason(modelId?: string, region?: WorkBuddyRegion): {
+    total: number;
+    cooling: number;
+    disabled: number;
+    reason: 'empty' | 'cooling' | 'disabled' | 'reserve' | 'none';
+  };
   /** Round-robin: the legacy cursor walk, kept for the distribution that asks for it. */
   private pickRoundRobin;
   /**

package/lib/index.js

@@ -2954,6 +2954,70 @@ var WorkBuddyAccountPool = class {
 			return true;
 		});
 	}
+	/**
+	* Why no account is available right now, for an accurate error.
+	*
+	* The pool can be empty for reasons that need OPPOSITE remedies: nobody is
+	* signed in (the user must sign in), every account is rate-limited (the user
+	* must wait, and retrying later works), or every account was switched off /
+	* ignored (the user must re-enable one). Reporting all of them as "no
+	* credential, sign in" sent users to re-authenticate over a temporary 429 —
+	* observed as an "API key invalid" panel for a model that was merely cooling.
+	*
+	* Counts are over the region's accounts, since a provider only ever sees its
+	* own gateway.
+	*/
+	unavailableReason(modelId, region) {
+		const now = Date.now();
+		const inRegion = this.accounts.filter((account) => region === void 0 || regionOf(account.credential.domain) === region);
+		if (inRegion.length === 0) return {
+			total: 0,
+			cooling: 0,
+			disabled: 0,
+			reason: "empty"
+		};
+		let cooling = 0;
+		let disabled = 0;
+		for (const account of inRegion) {
+			if (this.disabledIds.has(account.id)) {
+				disabled += 1;
+				continue;
+			}
+			const modelCooling = modelId !== void 0 && (account.modelCooldowns[modelId] ?? 0) > now;
+			if (account.cooldownUntilMs > now || modelCooling) {
+				cooling += 1;
+				continue;
+			}
+			const reserve = this.creditReserves.get(account.id);
+			if (reserve !== void 0 && reserve > 0) {
+				const balance = this.creditBalances.get(account.id);
+				if (balance !== void 0 && balance <= reserve) return {
+					total: inRegion.length,
+					cooling,
+					disabled,
+					reason: "reserve"
+				};
+			}
+		}
+		if (cooling > 0) return {
+			total: inRegion.length,
+			cooling,
+			disabled,
+			reason: "cooling"
+		};
+		if (disabled > 0) return {
+			total: inRegion.length,
+			cooling,
+			disabled,
+			reason: "disabled"
+		};
+		return {
+			total: inRegion.length,
+			cooling,
+			disabled,
+			reason: "none"
+		};
+	}
 	/** Round-robin: the legacy cursor walk, kept for the distribution that asks for it. */
 	pickRoundRobin(pool) {
 		const index = this.cursor % pool.length;
@@ -5548,6 +5612,40 @@ function isContextTooLong(body) {
 	if (/exceeds?\s+(the\s+)?(model\s+)?context\s+(window|limit)/iu.test(body)) return true;
 	return false;
 }
+/**
+* A content-free description of a request, for the log when the upstream
+* rejects it.
+*
+* `model_param_invalid` arrives with an EMPTY `param` field, so the error alone
+* says nothing about which parameter was rejected — the user is left with "the
+* request parameters do not meet the current model requirements" and no way to
+* act. Recording the shape (top-level keys, message count by role, tool count,
+* approximate prompt size) makes such a rejection diagnosable from the log.
+*
+* Deliberately SHAPE ONLY: no message content, no tool schemas, no tokens. It
+* ends up in a log file, and the conversation it describes is the user's.
+*/
+function requestShape(raw) {
+	try {
+		const parsed = JSON.parse(raw);
+		const keys = Object.keys(parsed).sort();
+		const messages = Array.isArray(parsed["messages"]) ? parsed["messages"] : [];
+		const byRole = /* @__PURE__ */ new Map();
+		let chars = 0;
+		for (const entry of messages) {
+			if (typeof entry !== "object" || entry === null) continue;
+			const message = entry;
+			const role = typeof message["role"] === "string" ? message["role"] : "?";
+			byRole.set(role, (byRole.get(role) ?? 0) + 1);
+			chars += JSON.stringify(message["content"] ?? "").length;
+		}
+		const roles = [...byRole.entries()].map(([role, n]) => `${role}:${n}`).join(" ");
+		const tools = Array.isArray(parsed["tools"]) ? parsed["tools"].length : 0;
+		return `keys=[${keys.join(" ")}] messages=${messages.length}${roles === "" ? "" : ` (${roles})`} tools=${tools} contentChars=${chars}`;
+	} catch {
+		return "body was not parseable JSON";
+	}
+}
 function readBody(req) {
 	return new Promise((resolve, reject) => {
 		const chunks = [];
@@ -5686,17 +5784,26 @@ function createWorkBuddyShim(options) {
 		}
 		const tried = [];
 		let last;
-		let exhaustedByRateLimit = false;
 		for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
 			if (controller.signal.aborted) return;
 			const account = await pool.acquire(modelId, region);
 			if (account === void 0) {
-				if (exhaustedByRateLimit && last !== void 0) {
+				const why = pool.unavailableReason(modelId, region);
+				if (why.reason === "cooling") {
 					const subject = modelId === void 0 ? "every WorkBuddy account is rate-limited" : `every account is rate-limited for model ${modelId}`;
-					writeOpenAIError(res, KIND_STATUS[last.kind], last.kind, `${subject} (tried ${tried.length}: ${tried.join(", ")}); resets at the upstream window — ${last.message.slice(0, 200)}`);
+					const upstream = last === void 0 ? "" : ` — ${last.message.slice(0, 200)}`;
+					writeOpenAIError(res, 429, "soft_rate", `${subject} (${why.cooling}/${why.total} cooling, tried ${tried.length})${tried.length === 0 ? "" : `: ${tried.join(" → ")}`}${upstream}`);
+					return;
+				}
+				if (why.reason === "disabled") {
+					writeOpenAIError(res, 403, "no_enabled_account", `all ${why.total} WorkBuddy account(s) for this gateway are switched off or ignored; re-enable one on the pool card`);
+					return;
+				}
+				if (why.reason === "reserve") {
+					writeOpenAIError(res, 402, "reserve_floor", `every WorkBuddy account is at or below its credit reserve (${why.total} account(s)); lower the reserve on the pool card or top up credits`);
 					return;
 				}
-				writeOpenAIError(res, 401, "not_signed_in", "no WorkBuddy credential found; sign in on the desktop app (or set WORKBUDDY_AUTH_FILE)");
+				writeOpenAIError(res, 401, "not_signed_in", why.total === 0 ? "no WorkBuddy credential found for this gateway; sign in on the desktop app (or set WORKBUDDY_AUTH_FILE)" : `no usable WorkBuddy credential among ${why.total} account(s) for this gateway; sign in again on the desktop app`);
 				return;
 			}
 			tried.push(account.label);
@@ -5720,8 +5827,8 @@ function createWorkBuddyShim(options) {
 				logger?.warn(`dsh-workbuddy-xdpool: ${account.label} has no credits left (attempt ${attempt + 1}/${maxAttempts}); rotating`);
 				continue;
 			}
+			if (result.kind === "client") logger?.warn(`dsh-workbuddy-xdpool: ${account.label} rejected the request as invalid (model ${modelId ?? "(none)"}) — ${requestShape(raw)}; upstream: ${result.message.slice(0, 300)}`);
 			if (result.kind !== "soft_rate") break;
-			exhaustedByRateLimit = true;
 			pool.penalize(account.id, parseRateLimitReset(result.message), modelId);
 			logger?.warn(`dsh-workbuddy-xdpool: ${account.label} rate-limited on ${modelId ?? "(no model)"} (attempt ${attempt + 1}/${maxAttempts}); rotating`);
 		}
@@ -5844,8 +5951,10 @@ async function recoverFromContextOverrun(options) {
 	};
 	const overrunTokens = estimateMessagesTokens(messages);
 	const realWindow = options.contextWindow;
-	const budget = realWindow !== void 0 && realWindow > 0 ? Math.max(512, Math.floor(realWindow * .8) - 2048) : Math.max(512, Math.floor(overrunTokens / 2));
-	logger?.warn(`dsh-workbuddy-xdpool: context overrun on ${modelId ?? "(no model)"} (~${overrunTokens} tokens); compacting to ~${budget} and retrying once`);
+	const fromWindow = realWindow !== void 0 && realWindow > 0 ? Math.max(512, Math.floor(realWindow * .8) - 2048) : Number.POSITIVE_INFINITY;
+	const fromOverrun = Math.max(512, Math.floor(overrunTokens / 2));
+	const budget = Math.min(fromWindow, fromOverrun);
+	logger?.warn(`dsh-workbuddy-xdpool: context overrun on ${modelId ?? "(no model)"} (~${overrunTokens} tokens, catalog window ${realWindow ?? "unknown"}); compacting to ~${budget} and retrying once`);
 	let summary;
 	let compacted = messages;
 	let compactionDetail = "";

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-workbuddy-xdpool",
   "displayName": "DSH WorkBuddy XD Pool",
   "description": "Merge every locally signed-in WorkBuddy account into DeepSeek Harness as one auto-failing-over model pool (multi-account rotation, live credits, daily check-in and model catalog).",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "license": "MIT",
   "author": "XDTrees",
   "homepage": "https://github.com/XDTrees/dsh-workbuddy-xdpool#readme",
@@ -25,7 +25,7 @@
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.5-rc.1 <0.2.0"
+    "dsh": ">=0.1.5-rc.1 <0.3.0"
   },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -99,9 +99,9 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-llm-pi-ai": ">=0.1.1-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-llm-pi-ai": ">=0.1.1-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.1 <0.3.0",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@earendil-works/pi-ai": ">=0.82.1"
   },