dsh-xdpool 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -1,15 +1,49 @@
 # Changelog
 本项目的所有重要变更都会记录在此文件。
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+## 2.4.1 — 11128 的真正成因：system 内容指纹
+> 2.4.0 之后仍有用户撞上 `400 / 11128 Illegal API invocation from an unapproved channel`。定位下来，2.4.0 的归因是错的，这一版修的是真原因。
+### 11128 不是身份头的问题，是 system 内容里的自报句
+网关按**内容指纹**判定「这是不是官方客户端发出来的」，命中串是 system 消息里的 `You are an AI agent powered by DeepSeek Harness`。它只匹配 `role === "system"`（放进 user/tool 不管），字面子串、大小写不敏感，且带起始位置倾向——放在提示词第一行会被拦，前面垫一行普通文字就放行。
+
+这句话由宿主的第一方插件 `@deepseek-ai/dsh-system-prompt` 固定注入，**任何未改装的安装都会 100% 命中**，与账号、密钥、渠道、UA 全部无关——这也解释了为什么它在「1 个账号失败后不再重试」：每个账号都会失败，重试没有意义。
+
+修法是在发送前把 system 里的这句改写成网关放行的同义句（`powered by` → `running on`），只动命中的文本块，图片/缓存块的引用原样透传；没命中时返回同一个引用，不为「什么都没改」付深拷贝代价。改写清单做成了数组，将来网关加句只是多一行。
+
+**实测（真实国内网关，同一账号三组对照）**：
+| 请求体 | 结果 |
+|---|---|
+| 经本插件改写 | `429 / 6004`（通过渠道校验，仅受频率限制） |
+| 原样含该句（对照） | `400 / 11128` |
+| system 干净（基线） | `429 / 6004` |
+
+### 国际网关要求首条消息是 system
+`www.workbuddy.ai` 对一个以 `user` 开头的请求体回 `400 / 11128 "first message is not system prompt"`，而**同一个请求体在国内网关是被接受的**。同一个错误码，两种完全不同成因——这正是不能只按业务码分支的原因。现在国际版请求若首条不是 system，会在最前面补一条占位 system，用户自己的消息位置和措辞一个字符都不动。
+
+### 思考档位「关闭」会被两区同时拒绝
+适配层把 `thinkingLevelMap.off` 钉成字面量 `'off'`，而 pi-ai 对「没有显式指定档位」的请求发的就是它——所以选「默认」和选「关闭」产生了同一个请求体。两区都不接受这个值：国际版 GPT 族回 `400 / 11133`（`extError.param === 'reasoning.effort'`），国内版在声明了 `onlyReasoning` 的模型上报错。现在发送前把它删掉，让上游走自己的默认档。**省略**是唯一在各个区、各个模型上都实测通过的写法；换成字面量 `'none'` 不是安全替代。
+
+**实测（真实双网关，同一账号前后对照）**：
+
+| 请求 | 修复前 | 修复后 |
+|---|---|---|
+| 国际版，首条为 user | `400 / 11128 first message is not system prompt` | `200` |
+| 国际版，`reasoning_effort: "off"` | `400 / 11133 extError.param=reasoning.effort` | `200` |
+
+### 免费模型限流提示：说清配额是按会话算的
+免费车道的拒绝原文是「the provider asked to wait 74558s」——二十小时，读起来像是整个免费车道被封了。实际配额**按上游会话计**，换一个会话（或换一个模型）就另有一份额度。现在限流错误的文案补上了这一句；只有限流类错误带这句，凭据失效、模型不存在之类加上去只会引导用户去做无用重试。
+### 其他
+- 测试：新增 system 指纹改写 8 例 + 区域专属请求体规则 12 例 + 免费车道会话配额提示 1 例，全套 71 文件 932 用例。
 ## 2.4.0 — 会话身份头、清单不再冻结、中文路由可存
 > 这一版收的是「用着用着就报错」的那一类问题：调用被网关判成非法渠道（11128）、国际版模型清单永远停在启动那一刻、中文名字的路由点了保存却没存下、上下文选择一选就弹回去。
-### 会话身份头：修掉 400 / 11128「Illegal API invocation from an unapproved channel」
-网关对「这一轮对话属于谁」有一组身份头，缺一个就整轮拒绝，报 `11128 Illegal API invocation from an unapproved channel`，看起来像密钥失效，其实是新会话没自报身份。补齐官方客户端的契约：
+### 会话身份头：补齐官方客户端的契约
+网关对「这一轮对话属于谁」有一组身份头。补齐官方客户端的契约：
 - **会话稳定三头**（同一会话内不变）：`X-Conversation-ID`、`X-Conversation-Request-ID`、`acp-connection-id`。
 - **每请求两头**（逐次随机）：`X-Conversation-Message-ID`、`X-Request-ID`。
 - 另附 `X-Agent-Intent`、`X-Agent-Purpose`、`x-codebuddy-request`、`X-Private-Data`、`X-Product` 与 W3C/B3 追踪族。
 
-实测口径：三个稳定头缺任一个即 400 11128，齐全即 200；值本身不校验（非 UUID 字符串也过）。池车道（WorkBuddy 国内/国际）与扫码渠道的 `send` 两条路径都已接上。
+> **口径更正（见 2.4.1）**：本版曾把 `400 / 11128` 归因于「缺会话身份头」。这个归因是错的——实测国内网关根本不检查这组头（不带任何身份头、system 干净时正常放行）。身份头照官方契约补齐没有坏处，但 11128 的真正成因是 system 内容里的自报句，已在 2.4.1 修掉。
+
 顺带修掉同源的一处：`role: "developer"` 的消息在国内网关同样触发 11128，现统一上送为 `system`。
 ### 国际版模型清单：不再冻结在启动那一刻
 `createProvider` 的 `models` 是在创建 provider 时快照下来的数组，而原来的 `invalidate()` 只重排了 profile、复用了同一个 provider 对象，宿主按对象身份记忆化 `current()`，于是**新拿到的模型清单永远送不到选择器**——表现是「重新获取模型」点了没反应、国际版清单停在开机那一刻。现在每次 `invalidate()` 重建 provider 与 profile 两个对象，并通过 adapter handle 的 `replace()` 重新登记路由，由宿主自己发出 `llm/adapters-updated`。

package/lib/bin.js

@@ -278,6 +278,90 @@ const CHAT_IDENTITY_HEADERS = Object.freeze({
 	"X-IDE-Version": "5.5.6"
 });
 /**
+* System-prompt strings the gateway treats as evidence of a non-official
+* client, and the rewriting that clears the check.
+*
+* WHY THIS EXISTS
+*
+* `code 11128 Illegal API invocation from an unapproved channel` has a SECOND
+* trigger, separate from the conversation-identity headers below: the gateway
+* matches the CONTENT of system messages against a list of strings that identify
+* other agents' clients. The first-party DSH system-prompt plugin injects
+* `You are an AI agent powered by DeepSeek Harness.` as the opening line of
+* every conversation, so every request from an unmodified install is rejected —
+* regardless of which account in the pool is used, which is why the reported
+* symptom was a 400 on the first account with no retry.
+*
+* Boundary, measured against the live domestic gateway (429 = accepted,
+* 400/11128 = blocked):
+*   - the match is a literal substring, BUT only near the START of a system
+*     message: the sentence blocked a longer prompt when it was the first line,
+*     and passed when one plain line was prepended to it ("trailing text after
+*     it" above is the same finding from the other side).
+*   - it is case-insensitive (`you are an ai agent powered by deepseek harness`
+*     is blocked too).
+*   - only `role: "system"` is inspected: the same sentence in a `user` or
+*     `tool` message passes, and it is blocked in a second system message too.
+*   - `deepseek harness` alone, or `powered by deepseek` alone, passes — the
+*     whole phrase is what matches.
+*   - replacing `powered by` with `running on` passes, which is the rewrite
+*     below: it keeps the meaning for the model and shares no substring with
+*     the fingerprint.
+*
+* A prepended blank line would equally defeat a start-anchored check, but it
+* would leave the banned string in the body: the list is server-side and may
+* lose its anchor tomorrow. Rewriting the phrase is what the report's repro
+* verified, so that is what this does.
+*
+* The list is an ARRAY because these fingerprints are appended to over time; a
+* future rejection should be one more row here, not a new code path.
+*/
+const BANNED_SYSTEM_PHRASES = Object.freeze([[/powered by DeepSeek Harness/gi, "running on DeepSeek Harness"]]);
+/**
+* Rewrite fingerprinted system content, leaving everything else byte-identical.
+*
+* System content arrives as either a plain string or an array of content blocks
+* (an OpenAI-compatible body allows both), so both shapes are handled — fixing
+* only the string form would miss every request that carries an image or a
+* cache-control block.
+*
+* Returns the SAME reference when nothing matched: a long conversation's system
+* prompt can be large, and paying for a deep copy to change nothing is waste.
+* Only matched `text` blocks are rebuilt; image and cache blocks pass through
+* untouched so the request shape survives.
+*/
+function sanitizeSystemContent(content) {
+	if (typeof content === "string") return sanitizeSystemText(content);
+	if (!Array.isArray(content)) return content;
+	let changed = false;
+	const next = content.map((block) => {
+		if (typeof block !== "object" || block === null || Array.isArray(block)) return block;
+		const record = block;
+		const text = record["text"];
+		if (typeof text !== "string") return block;
+		const cleaned = sanitizeSystemText(text);
+		if (cleaned === text) return block;
+		changed = true;
+		return {
+			...record,
+			text: cleaned
+		};
+	});
+	return changed ? next : content;
+}
+/**
+* Apply every banned-phrase rewrite to one string.
+*
+* The RegExp is rebuilt per call on purpose: a shared `g`-flagged instance
+* carries `lastIndex` between calls, so the second request in a conversation
+* could skip a match the first one caught.
+*/
+function sanitizeSystemText(text) {
+	let out = text;
+	for (const [pattern, replacement] of BANNED_SYSTEM_PHRASES) out = out.replace(new RegExp(pattern.source, pattern.flags), replacement);
+	return out;
+}
+/**
 * The conversation-identity headers the gateway's channel check demands.
 *
 * WHY THIS EXISTS
@@ -878,7 +962,15 @@ var WorkBuddyUpstreamClient = class {
 	* Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
 	* force `stream: true` (the upstream rejects non-streaming), convert the
 	* DSH `developer` role into `system` (upstream rejects `developer` with
-	* business code 11128), and flatten `tool_choice` into its string form.
+	* business code 11128), rewrite system content the gateway fingerprints as a
+	* non-official client (also 11128), and flatten `tool_choice` into its string
+	* form.
+	*
+	* This is the REGION-BLIND half. Everything here is measured good on both
+	* gateways, so it runs before the region is known — the pool lane picks its
+	* account after this call. The two region-only rules live in
+	* {@link prepareChatBodyFor} instead; see its comment for why they cannot be
+	* folded in here.
 	*/
 	prepareChatBody(raw) {
 		let body;
@@ -897,6 +989,7 @@ var WorkBuddyUpstreamClient = class {
 			if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
 			const message = value;
 			if (message["role"] === "developer") message["role"] = "system";
+			if (message["role"] === "system") message["content"] = sanitizeSystemContent(message["content"]);
 		}
 		const choice = obj["tool_choice"];
 		if (typeof choice === "string") {
@@ -923,6 +1016,61 @@ var WorkBuddyUpstreamClient = class {
 		return JSON.stringify(obj);
 	}
 	/**
+	* The region-only half of body normalisation, applied once the account is
+	* known.
+	*
+	* WHY IT IS SEPARATE
+	*
+	* The pool lane calls {@link prepareChatBody} BEFORE it picks an account —
+	* the body has to be ready for whichever account wins. So anything that
+	* depends on the region cannot live there. Two rules do:
+	*
+	* 1. **International requires a leading `system`.** Measured: a body whose
+	*    first message is `user` answers `400 / 11128 "first message is not
+	*    system prompt"` on `www.workbuddy.ai`, while the identical body is
+	*    accepted on the domestic gateway. Same code, different cause — the
+	*    domestic gateway uses 11128 for the `developer` role and for the
+	*    content fingerprint, which is why nothing may branch on the code alone.
+	*    A placeholder assistant prompt is prepended, never merged: every
+	*    caller-supplied message keeps its position and wording.
+	*
+	* 2. **Neither gateway accepts `reasoning_effort: "off"`.** The adapter pins
+	*    `thinkingLevelMap.off` to the literal `'off'` so the level stays
+	*    selectable, and pi-ai emits that value for any request carrying no
+	*    explicit level — so "Default" and "Off" produce the same body.
+	*    Measured: the international GPT family answers `400 / 11133`
+	*    (`extError.param === 'reasoning.effort'`), and the domestic gateway
+	*    rejects it on models that declare `onlyReasoning`. Omission is the only
+	*    spelling measured good everywhere; a literal `'none'` is NOT a safe
+	*    substitute (accepted by the GPT-5.6 family, rejected by others).
+	*
+	* Both rules are no-ops on a body that already complies, so this is safe to
+	* run over an already-prepared body.
+	*/
+	prepareChatBodyFor(raw, region) {
+		const prepared = this.prepareChatBody(raw);
+		let body;
+		try {
+			body = JSON.parse(prepared);
+		} catch {
+			return prepared;
+		}
+		if (typeof body !== "object" || body === null || Array.isArray(body)) return prepared;
+		const obj = body;
+		if (obj["reasoning_effort"] === "off") delete obj["reasoning_effort"];
+		if (region === "global") {
+			const messages = obj["messages"];
+			if (Array.isArray(messages)) {
+				const first = messages[0];
+				if (!(typeof first === "object" && first !== null && !Array.isArray(first) && first["role"] === "system")) messages.unshift({
+					role: "system",
+					content: "You are a helpful assistant."
+				});
+			}
+		}
+		return JSON.stringify(obj);
+	}
+	/**
 	* Parse a raw OpenAI chat body without normalising it.
 	*
 	* The compactor needs the message array as objects, while `chatStream` only
@@ -938,12 +1086,20 @@ var WorkBuddyUpstreamClient = class {
 		if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
 		return body;
 	}
-	/** Re-serialise `base` with a rewritten `messages` array, still normalised. */
-	buildChatBody(base, messages) {
-		return this.prepareChatBody(JSON.stringify({
+	/**
+	* Re-serialise `base` with a rewritten `messages` array, still normalised.
+	*
+	* `region` is optional so the composite lanes (aggregate / free) can keep
+	* calling it without one; when supplied, the region-only rules of
+	* {@link prepareChatBodyFor} ride along. Both in-repo callers are the
+	* compaction paths, which always know their shim's region.
+	*/
+	buildChatBody(base, messages, region) {
+		const raw = JSON.stringify({
 			...base,
 			messages
-		}));
+		});
+		return region === void 0 ? this.prepareChatBody(raw) : this.prepareChatBodyFor(raw, region);
 	}
 	/**
 	* Run one NON-streaming completion and return the assistant text.

package/lib/client.js

@@ -12188,7 +12188,7 @@ window.__ModuleLoader__.load({
 		*
 		* @module dsh-xdpool/version
 		*/
-		const POOL_VERSION = "2.4.0";
+		const POOL_VERSION = "2.4.1";
 		//#endregion
 		//#region src/client/PoolCard.tsx
 		/**

package/lib/index.d.ts

@@ -469,9 +469,50 @@ export declare class WorkBuddyUpstreamClient {
    * Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
    * force `stream: true` (the upstream rejects non-streaming), convert the
    * DSH `developer` role into `system` (upstream rejects `developer` with
-   * business code 11128), and flatten `tool_choice` into its string form.
+   * business code 11128), rewrite system content the gateway fingerprints as a
+   * non-official client (also 11128), and flatten `tool_choice` into its string
+   * form.
+   *
+   * This is the REGION-BLIND half. Everything here is measured good on both
+   * gateways, so it runs before the region is known — the pool lane picks its
+   * account after this call. The two region-only rules live in
+   * {@link prepareChatBodyFor} instead; see its comment for why they cannot be
+   * folded in here.
    */
   prepareChatBody(raw: string): string;
+  /**
+   * The region-only half of body normalisation, applied once the account is
+   * known.
+   *
+   * WHY IT IS SEPARATE
+   *
+   * The pool lane calls {@link prepareChatBody} BEFORE it picks an account —
+   * the body has to be ready for whichever account wins. So anything that
+   * depends on the region cannot live there. Two rules do:
+   *
+   * 1. **International requires a leading `system`.** Measured: a body whose
+   *    first message is `user` answers `400 / 11128 "first message is not
+   *    system prompt"` on `www.workbuddy.ai`, while the identical body is
+   *    accepted on the domestic gateway. Same code, different cause — the
+   *    domestic gateway uses 11128 for the `developer` role and for the
+   *    content fingerprint, which is why nothing may branch on the code alone.
+   *    A placeholder assistant prompt is prepended, never merged: every
+   *    caller-supplied message keeps its position and wording.
+   *
+   * 2. **Neither gateway accepts `reasoning_effort: "off"`.** The adapter pins
+   *    `thinkingLevelMap.off` to the literal `'off'` so the level stays
+   *    selectable, and pi-ai emits that value for any request carrying no
+   *    explicit level — so "Default" and "Off" produce the same body.
+   *    Measured: the international GPT family answers `400 / 11133`
+   *    (`extError.param === 'reasoning.effort'`), and the domestic gateway
+   *    rejects it on models that declare `onlyReasoning`. Omission is the only
+   *    spelling measured good everywhere; a literal `'none'` is NOT a safe
+   *    substitute (accepted by the GPT-5.6 family, rejected by others).
+   *
+   * Both rules are no-ops on a body that already complies, so this is safe to
+   * run over an already-prepared body.
+   */
+  prepareChatBodyFor(raw: string, region: WorkBuddyRegion): string;
   /**
    * Parse a raw OpenAI chat body without normalising it.
    *
@@ -479,8 +520,15 @@ export declare class WorkBuddyUpstreamClient {
    * accepts the serialised string form.
    */
   parseChatBody(raw: string): Record<string, unknown> | undefined;
-  /** Re-serialise `base` with a rewritten `messages` array, still normalised. */
-  buildChatBody(base: Record<string, unknown>, messages: readonly ChatMessage[]): string;
+  /**
+   * Re-serialise `base` with a rewritten `messages` array, still normalised.
+   *
+   * `region` is optional so the composite lanes (aggregate / free) can keep
+   * calling it without one; when supplied, the region-only rules of
+   * {@link prepareChatBodyFor} ride along. Both in-repo callers are the
+   * compaction paths, which always know their shim's region.
+   */
+  buildChatBody(base: Record<string, unknown>, messages: readonly ChatMessage[], region?: WorkBuddyRegion): string;
   /**
    * Run one NON-streaming completion and return the assistant text.
    *

package/lib/index.js

@@ -329,6 +329,90 @@ const CHAT_IDENTITY_HEADERS = Object.freeze({
 	"X-IDE-Version": "5.5.6"
 });
 /**
+* System-prompt strings the gateway treats as evidence of a non-official
+* client, and the rewriting that clears the check.
+*
+* WHY THIS EXISTS
+*
+* `code 11128 Illegal API invocation from an unapproved channel` has a SECOND
+* trigger, separate from the conversation-identity headers below: the gateway
+* matches the CONTENT of system messages against a list of strings that identify
+* other agents' clients. The first-party DSH system-prompt plugin injects
+* `You are an AI agent powered by DeepSeek Harness.` as the opening line of
+* every conversation, so every request from an unmodified install is rejected —
+* regardless of which account in the pool is used, which is why the reported
+* symptom was a 400 on the first account with no retry.
+*
+* Boundary, measured against the live domestic gateway (429 = accepted,
+* 400/11128 = blocked):
+*   - the match is a literal substring, BUT only near the START of a system
+*     message: the sentence blocked a longer prompt when it was the first line,
+*     and passed when one plain line was prepended to it ("trailing text after
+*     it" above is the same finding from the other side).
+*   - it is case-insensitive (`you are an ai agent powered by deepseek harness`
+*     is blocked too).
+*   - only `role: "system"` is inspected: the same sentence in a `user` or
+*     `tool` message passes, and it is blocked in a second system message too.
+*   - `deepseek harness` alone, or `powered by deepseek` alone, passes — the
+*     whole phrase is what matches.
+*   - replacing `powered by` with `running on` passes, which is the rewrite
+*     below: it keeps the meaning for the model and shares no substring with
+*     the fingerprint.
+*
+* A prepended blank line would equally defeat a start-anchored check, but it
+* would leave the banned string in the body: the list is server-side and may
+* lose its anchor tomorrow. Rewriting the phrase is what the report's repro
+* verified, so that is what this does.
+*
+* The list is an ARRAY because these fingerprints are appended to over time; a
+* future rejection should be one more row here, not a new code path.
+*/
+const BANNED_SYSTEM_PHRASES = Object.freeze([[/powered by DeepSeek Harness/gi, "running on DeepSeek Harness"]]);
+/**
+* Rewrite fingerprinted system content, leaving everything else byte-identical.
+*
+* System content arrives as either a plain string or an array of content blocks
+* (an OpenAI-compatible body allows both), so both shapes are handled — fixing
+* only the string form would miss every request that carries an image or a
+* cache-control block.
+*
+* Returns the SAME reference when nothing matched: a long conversation's system
+* prompt can be large, and paying for a deep copy to change nothing is waste.
+* Only matched `text` blocks are rebuilt; image and cache blocks pass through
+* untouched so the request shape survives.
+*/
+function sanitizeSystemContent(content) {
+	if (typeof content === "string") return sanitizeSystemText(content);
+	if (!Array.isArray(content)) return content;
+	let changed = false;
+	const next = content.map((block) => {
+		if (typeof block !== "object" || block === null || Array.isArray(block)) return block;
+		const record = block;
+		const text = record["text"];
+		if (typeof text !== "string") return block;
+		const cleaned = sanitizeSystemText(text);
+		if (cleaned === text) return block;
+		changed = true;
+		return {
+			...record,
+			text: cleaned
+		};
+	});
+	return changed ? next : content;
+}
+/**
+* Apply every banned-phrase rewrite to one string.
+*
+* The RegExp is rebuilt per call on purpose: a shared `g`-flagged instance
+* carries `lastIndex` between calls, so the second request in a conversation
+* could skip a match the first one caught.
+*/
+function sanitizeSystemText(text) {
+	let out = text;
+	for (const [pattern, replacement] of BANNED_SYSTEM_PHRASES) out = out.replace(new RegExp(pattern.source, pattern.flags), replacement);
+	return out;
+}
+/**
 * The conversation-identity headers the gateway's channel check demands.
 *
 * WHY THIS EXISTS
@@ -1038,7 +1122,15 @@ var WorkBuddyUpstreamClient = class {
 	* Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
 	* force `stream: true` (the upstream rejects non-streaming), convert the
 	* DSH `developer` role into `system` (upstream rejects `developer` with
-	* business code 11128), and flatten `tool_choice` into its string form.
+	* business code 11128), rewrite system content the gateway fingerprints as a
+	* non-official client (also 11128), and flatten `tool_choice` into its string
+	* form.
+	*
+	* This is the REGION-BLIND half. Everything here is measured good on both
+	* gateways, so it runs before the region is known — the pool lane picks its
+	* account after this call. The two region-only rules live in
+	* {@link prepareChatBodyFor} instead; see its comment for why they cannot be
+	* folded in here.
 	*/
 	prepareChatBody(raw) {
 		let body;
@@ -1057,6 +1149,7 @@ var WorkBuddyUpstreamClient = class {
 			if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
 			const message = value;
 			if (message["role"] === "developer") message["role"] = "system";
+			if (message["role"] === "system") message["content"] = sanitizeSystemContent(message["content"]);
 		}
 		const choice = obj["tool_choice"];
 		if (typeof choice === "string") {
@@ -1083,6 +1176,61 @@ var WorkBuddyUpstreamClient = class {
 		return JSON.stringify(obj);
 	}
 	/**
+	* The region-only half of body normalisation, applied once the account is
+	* known.
+	*
+	* WHY IT IS SEPARATE
+	*
+	* The pool lane calls {@link prepareChatBody} BEFORE it picks an account —
+	* the body has to be ready for whichever account wins. So anything that
+	* depends on the region cannot live there. Two rules do:
+	*
+	* 1. **International requires a leading `system`.** Measured: a body whose
+	*    first message is `user` answers `400 / 11128 "first message is not
+	*    system prompt"` on `www.workbuddy.ai`, while the identical body is
+	*    accepted on the domestic gateway. Same code, different cause — the
+	*    domestic gateway uses 11128 for the `developer` role and for the
+	*    content fingerprint, which is why nothing may branch on the code alone.
+	*    A placeholder assistant prompt is prepended, never merged: every
+	*    caller-supplied message keeps its position and wording.
+	*
+	* 2. **Neither gateway accepts `reasoning_effort: "off"`.** The adapter pins
+	*    `thinkingLevelMap.off` to the literal `'off'` so the level stays
+	*    selectable, and pi-ai emits that value for any request carrying no
+	*    explicit level — so "Default" and "Off" produce the same body.
+	*    Measured: the international GPT family answers `400 / 11133`
+	*    (`extError.param === 'reasoning.effort'`), and the domestic gateway
+	*    rejects it on models that declare `onlyReasoning`. Omission is the only
+	*    spelling measured good everywhere; a literal `'none'` is NOT a safe
+	*    substitute (accepted by the GPT-5.6 family, rejected by others).
+	*
+	* Both rules are no-ops on a body that already complies, so this is safe to
+	* run over an already-prepared body.
+	*/
+	prepareChatBodyFor(raw, region) {
+		const prepared = this.prepareChatBody(raw);
+		let body;
+		try {
+			body = JSON.parse(prepared);
+		} catch {
+			return prepared;
+		}
+		if (typeof body !== "object" || body === null || Array.isArray(body)) return prepared;
+		const obj = body;
+		if (obj["reasoning_effort"] === "off") delete obj["reasoning_effort"];
+		if (region === "global") {
+			const messages = obj["messages"];
+			if (Array.isArray(messages)) {
+				const first = messages[0];
+				if (!(typeof first === "object" && first !== null && !Array.isArray(first) && first["role"] === "system")) messages.unshift({
+					role: "system",
+					content: "You are a helpful assistant."
+				});
+			}
+		}
+		return JSON.stringify(obj);
+	}
+	/**
 	* Parse a raw OpenAI chat body without normalising it.
 	*
 	* The compactor needs the message array as objects, while `chatStream` only
@@ -1098,12 +1246,20 @@ var WorkBuddyUpstreamClient = class {
 		if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
 		return body;
 	}
-	/** Re-serialise `base` with a rewritten `messages` array, still normalised. */
-	buildChatBody(base, messages) {
-		return this.prepareChatBody(JSON.stringify({
+	/**
+	* Re-serialise `base` with a rewritten `messages` array, still normalised.
+	*
+	* `region` is optional so the composite lanes (aggregate / free) can keep
+	* calling it without one; when supplied, the region-only rules of
+	* {@link prepareChatBodyFor} ride along. Both in-repo callers are the
+	* compaction paths, which always know their shim's region.
+	*/
+	buildChatBody(base, messages, region) {
+		const raw = JSON.stringify({
 			...base,
 			messages
-		}));
+		});
+		return region === void 0 ? this.prepareChatBody(raw) : this.prepareChatBodyFor(raw, region);
 	}
 	/**
 	* Run one NON-streaming completion and return the assistant text.
@@ -13440,6 +13596,24 @@ function freeFetch(url, init = {}) {
 	});
 }
 /**
+* Add the one fact a 429 on this lane can never convey on its own.
+*
+* The free tier meters quota PER UPSTREAM SESSION, not per key and not per
+* account — the gateway's own sentence is "the provider asked to wait 74558s",
+* i.e. twenty hours, which reads like a ban on the whole provider. It is not:
+* a different conversation maps to a different session and is served
+* immediately. Saying so costs one clause and turns a message that looks like
+* "this lane is over" into one that tells the user what to do next.
+*
+* Only a rate class gets the hint: a dead credential or a missing model has
+* nothing to do with the session budget, and adding the clause there would
+* invite the user to retry something that cannot succeed.
+*/
+function withSessionQuotaHint(error, retryAfterMs) {
+	if (!(error instanceof AggregateError) || error.kind !== "soft_rate" || retryAfterMs === void 0 || error.message.includes("per conversation")) return error;
+	return new AggregateError(error.kind, `${error.message} — this quota is counted per conversation on the free tier, so a new conversation (or another model) starts with its own budget`, error.status);
+}
+/**
 * POST one streaming turn and hand back chat-shaped deltas.
 *
 * The shape of the ANSWER decides how it is read, never its Content-Type: a front
@@ -13483,7 +13657,7 @@ async function postFreeStreamed({ modelId, body, session, requestId, hooks, plan
 	const retryAfter = retryAfterMs(response);
 	if (!response.ok) {
 		const refusal = await response.text().catch(() => "");
-		throw classifyUpstream(response.status, refusal, retryAfter, "");
+		throw withSessionQuotaHint(classifyUpstream(response.status, refusal, retryAfter, ""), retryAfter);
 	}
 	if (response.body === null) throw new AggregateError("server", "the free lane returned no body", response.status);
 	let events;
@@ -13516,7 +13690,7 @@ async function postFreeStreamed({ modelId, body, session, requestId, hooks, plan
 		} catch {
 			continue;
 		}
-		if (isRecord$1(decoded) && (decoded.error !== void 0 || decoded.type === "error")) throw classifyUpstream(response.status, event, retryAfter, "");
+		if (isRecord$1(decoded) && (decoded.error !== void 0 || decoded.type === "error")) throw withSessionQuotaHint(classifyUpstream(response.status, event, retryAfter, ""), retryAfter);
 		const translated = chatChunksFor(wire, decoded, tools);
 		for (const delta of translated.frames) hooks.onDelta(delta);
 		if (translated.usage !== void 0) usage = translated.usage;
@@ -18329,7 +18503,7 @@ function createWorkBuddyShim(options) {
 					};
 					continue;
 				}
-				const prepared = client.prepareChatBody(raw);
+				const prepared = client.prepareChatBodyFor(raw, region ?? "cn");
 				const result = await client.chatStream(account.credential, prepared, signal, conversationKey);
 				if (result.ok) {
 					const turnId = randomBytes(8).toString("hex");
@@ -18453,7 +18627,7 @@ function createWorkBuddyShim(options) {
 			writeOpenAIError(res, 503, `${lane}_unavailable`, lane === "free" ? `${modelId} is not available right now; the free lane's model listing is refreshed on the XD Pool card` : `${modelId} is not available right now; sign in to the co-paid lane on the XD Pool card`);
 			return;
 		}
-		const prepared = client.prepareChatBody(raw);
+		const prepared = client.prepareChatBodyFor(raw, region ?? "cn");
 		const conversationKey = conversationKeyOf(raw);
 		const tried = [];
 		let last;
@@ -18750,7 +18924,7 @@ async function recoverFromContextOverrun(options) {
 					...parsed,
 					stream: true,
 					max_tokens: Math.max(256, Math.floor(budget / 2))
-				}, request);
+				}, request, region ?? "cn");
 				return await client.completeChat(summariser.credential, body, signal ?? controller.signal, conversationKeyOf(raw));
 			} }, controller.signal);
 			compacted = outcome.messages;
@@ -18765,7 +18939,7 @@ async function recoverFromContextOverrun(options) {
 		ok: false,
 		detail: compactionDetail === "" ? "compaction could not reduce the prompt" : compactionDetail
 	};
-	const retryBody = client.buildChatBody(parsed, compacted);
+	const retryBody = client.buildChatBody(parsed, compacted, region ?? "cn");
 	const tried = [];
 	for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
 		if (controller.signal.aborted) return {

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-xdpool",
   "displayName": "DSH XD Pool",
   "description": "One DSH model pool for every free quota you have: merge all locally signed-in WorkBuddy accounts with auto-failover, sign in to 13 vendors by QR/web, aggregate 76 vendors' free tiers, plus a usage dashboard, model routing, a local OpenAI-compatible gateway and a points-automation suite.",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "license": "MIT",
   "author": "XDTrees",
   "homepage": "https://github.com/XDTrees/dsh-xdpool#readme",