dsh-connect-trae 4.6.2 → 4.6.4

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 4.6.4 (2026-10-28)
+
+> **缓存命中恒为 0% 不是插件丢了数字，是上游没有分配缓存池。** Trae 的
+> `metadata` 事件里 `prompt_cache_pool_record` 非空才代表这次请求挂了前缀
+> 缓存池；实测 CN/AI 双区、4 个账号、7 个模型、4 种 function，该字段
+> **100% 为 `null`**。没有池，`cache_read_input_tokens` 只能是 0 —— 0% 是
+> 正确读数。本版把这个事实变成可观测的，用户不必再怀疑插件吞了数据。
+
+### 修复
+
+- **上游的缓存池事实与管线名不再被丢弃**（#67）。
+  - **现象**：无论简单还是复杂提问，缓存命中恒为 0%，十个会话一致；
+    同时 tps 在 60–80 之间浮动。
+  - **根因**：不是插件。issue #10 的转发修复仍在（`lib/index.js` 含
+    `cached_tokens`，同版本下 `workbuddy`/`dsh-opencode-go` 命中显示正常），
+    是上游 `llm_utils_chat` 改由 `llm_raw_chat_v2` 管线、火山方舟 `ep-…`
+    端点承载后，不再为这些请求分配前缀缓存池。当初产出 5248/9216 的
+    `scripts/probe-cache-convention.mjs` 原样重跑，现在三轮全是 0。
+  - **修法**：`sse.ts` 新增 `diagnostic` 事件类型，解码 `metadata`
+    （`prompt_cache_pool_record`）与 `timing_cost`（`name` 管线名、
+    `provider_model_name`）；`solo-bridge.ts` 通过可选 `log` 上报
+    `promptCachePoolRecord` / `pipeline` / `providerModelName`；
+    `index.ts` 四个 `TraeSoloBridge` 构造点接入 `ctx.logger.warn`。
+    诊断事件不进答案文本、不改 usage 映射，**对外行为不变**。
+  - **为什么区分 `null` 与「字段不存在」**：`null` 是上游明确表示「没挂池」，
+    字段缺失只是没这条信息；两者混为一谈就又回到「看不出是谁的问题」。
+
+### 修复（顺带守住一个回归）
+
+- **`metadata` 不能被 peek 当成「上游已应答」**。它现在是被认识的事件类型，
+  若据此停止 peek，紧跟其后的拒绝（如 `1005` 未订阅）会退化成截断的 200 流
+  —— 正是 issue #19 的故障形态。`openTraeSource` 显式把 `diagnostic` 排除在
+  「已应答」之外。
+
+### 测试
+
+- `tests/sse.spec.ts`：`metadata` / `timing_cost` 解码为 `diagnostic`，
+  保留 `prompt_cache_pool_record: null`，且区分字段缺失。
+- `tests/solo-bridge.spec.ts`：诊断事实上报（含 `null` 原样保留、事件不泄漏进
+  答案）；`metadata` 之后紧跟的 `1005` 仍转成 402 `hard_credit`。
+
+### 说明
+
+- 诊断细节与完整证据链见 `docs/ISSUE67_DIAGNOSIS.md`（不随 npm 包发布）。
+- 上游若开始分配缓存池，`cached_tokens` 会自动恢复显示，插件侧无需再改。
+
+## 4.6.3 (2026-10-27)
+
+> **国际版美国区账号不会再被当成新加坡区。** 它的凭据明明写着
+> `host = https://grow-normal.traeapi.us`、`userRegion = "US"`，插件却因为
+> 「不认识 US」回落到 edition 标签（`sg → ai`），把 US token 发去 `*.trae.ai`
+> ——那边只会回 401；刷新模型拿到的 401 又被路由包成 500。用户看到的是
+> 「拉模型失败，请重新登录」，而重登拿到的还是同一份 US 凭据，于是无限循环。
+
+### 修复
+
+- **美国区成为显式区域，不再静默回退成新加坡区**（#66）。
+  - **现象**：`pay_status` 401；「刷新模型」500
+    `{"error":"SOLO remote models returned HTTP 401"}`；宿主日志
+    `live ai model directory unavailable; serving the configured catalog`。
+  - **根因**：`regionOfUserRegion` 只认 CN/SG、`regionOfHost` 只认
+    `.trae.ai`/`.trae.cn`，两级都落空后由 `regionOfEdition("sg")` 决定——
+    US 被判定为 `ai`。而 `REGION_GATEWAYS` 只有 cn/ai 两个键，于是「查不到」
+    变成了「拿另一个区的网关」。
+  - **修法**：新增 `TraeServiceRegion = 'cn' | 'ai' | 'us'`；`TraeRegion`
+    （存储/路由桶）仍是 `cn | ai`。`assertSupportedRegion()` 是唯一从区域
+    身份进到路由桶的入口，US 在**选择网关之前**抛
+    `TraeUnsupportedRegionError`。所有读网关的客户端（用量、SOLO wire、远程
+    目录、Raw Chat、IDE 名册）都走这一道，注入 `baseUrl` 的测试/诊断路径也
+    不例外。
+  - **为什么不是一行 `us → ai` 映射**：`ai` 的网关/目录/chat 契约都是按新加坡
+    实测出来的，而报告里的 US 实测恰好相反（远程目录 404、`llm_utils_chat`
+    403 `40006`、`create_agent_task` 的 config 绑定未知）。映射过去只是换一种
+    方式发错请求。**美国区本身仍未接入**，本版只保证它不再被误路由。
+
+- **上游 401/403 不再被包成 500**（#66）。
+  - 新增 `src/failure.ts`：`TraeHttpError` 携带上游状态，`httpFailureOf()` 把
+    401/403 映射为原状态 + `code: authentication`，本地「区域不支持」映射为
+    501 + `code: unsupported-region`，真正没有状态可言的失败仍 500。状态、
+    额度、账号表、模型刷新、模型测速、签到与账号池签到/测速这些路由全部改用
+    它。
+  - 卡片改为显示**服务端原文**（账号刷新、模型刷新、状态读取），不再只打印
+    `HTTP 401`——「网关拒绝了你」和「插件坏了」从此可以分辨。
+
+- **US 凭据不可选中、不计费，但会被点名**（#66）。
+  - `readAll()` 过滤掉本版本不服务的区域（作用域与无作用域 store 都过滤），
+    因此它不会被 refresh、不会进账号表、不会发出任何请求；
+    `unsupportedCredentials()` 单独把它读出来给卡片点名。
+  - 未登录态显示「美国区（US）暂不支持」并列出账号名，写明请求不会发往新加坡
+    网关、重新登录没有变化；诊断面板多一行「未支持的区域」。
+  - `resolve()` 在「只有 US 凭据」时抛明确错误，而不是笼统的
+    `no signed-in account found`；导入的区域门控同步把 `us` 当外区跳过。
+
+### 测试
+
+- `tests/issue66-us-region.spec.ts`（23 例）：US 的三条解析路径（claim / host /
+  完整凭据）都得到 `us` 而不是 `ai`；`payStatus` / 远程目录 / wire 名册 /
+  Raw Chat / chat 面对 US 凭据**零 `fetch` 调用**（含注入 `baseUrl` 的两例）；
+  作用域与无作用域 store 都不解析它、但都能点名；401/403/404/US/普通异常的
+  状态映射；模型刷新路由逐条断言 401、501、500；状态文档携带通告且不重复英文
+  异常文本。
+- `tests/issue66-card-us-notice.spec.tsx`（2 例）：未登录文档带
+  `unsupportedRegion` 时卡片点名账号；失败请求显示服务端 `error` 原文而非
+  `HTTP 401`。
+- **变异验证**：去掉 `regionOfUserRegion` 的 US 分支 → 2 例转红；刷新路由的
+  `failJson()` 改回 500 → 2 例转红；删掉 `readAll()` 的区域守卫 → 1 例转红。
+- 全量 **95 files / 1211 tests** 通过（原 93 / 1186 + 新增 2 files / 25 例）。
+
+### 说明
+
+- **没有对 US 网关发过真机请求**：开发机没有美国区凭据。结论来自报告人给出的
+  实测对照（同一 token 打 US 200、打 SG 401）与代码路径；测试断言的是「不会
+  发出请求」，不是模拟 US 响应。
+- 美国区的目录与 chat 仍待接入：目录需要 `get_detail_param` 的 `function`
+  单数 + `agent_type: null` 形态，chat 需要一次 IDE 侧的 `/api/agent/*`
+  实抓。拿到报文后即可按现有 `REGION_GATEWAYS` 的形状补齐。
+- 诊断与取舍全文见仓库内 `docs/ISSUE66_DIAGNOSIS.md`（该文档不随包发布）。
+
 ## 4.6.2 (2026-10-27)
 
 > **从插件市场装完，重启后插件不会再消失。** 安装其实失败了，但失败发生在

package/README.en.md

@@ -43,7 +43,7 @@ A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) bund
 - **Promotion badge** — Trae publishes its discount rules in the model directory (`activity_discount`: pay ratio, list price, off-peak windows with their time zone). The plugin judges them against **the clock at render time** and paints one capsule beside the model name (`5 折` / `off-peak 5 折` / `limited 5 折`), with the old price, the new price and the window on hover. Judging at render time is what keeps a night-time discount from still hanging there the next morning; when upstream says nothing is discounted right now no badge is painted, the multiplier is never used to guess a promotion, and no campaign without an end time is labelled "limited". It is information only: no request and no billing changes, and the international region (subscription) has no such data and therefore shows no badge. See [docs/PROMO_BADGE.md](docs/PROMO_BADGE.md).
 - **DSH local tool loop** — gets pending structured `tool_calls` from Trae `llm_utils_chat`, lets DSH execute its own local tools, then returns tool results to the model.
 - **Text-to-image (`trae_draw_image`)** — brings the signed-in account's Trae text-to-image service into the conversation: the model draws one image and the plugin **fetches the bytes too**, writes them under the session cwd and shows the picture inline. **Off by default, enabled per panel** — generation really spends credits (measured: ~8.8 for one `1920x1920` on CN personal), so unlike the image-input declaration it only happens when you say so. Protocol, size bounds, the two-step fetch and why the old "fetch" GET is really a second generation are in "Text-to-image" below.
-- **Dual-region detection (CN / international)** — detects local sign-ins across Trae CN, TRAE SOLO CN, Trae, and TRAE SOLO installs. The region is derived from the credential's own `userRegion` claim (host suffix and edition label as fallbacks), with no manual switch.
+- **Dual-region detection (CN / international)** — detects local sign-ins across Trae CN, TRAE SOLO CN, Trae, and TRAE SOLO installs. The region is derived from the credential's own `userRegion` claim (host suffix and edition label as fallbacks), with no manual switch. **The US cluster (`userRegion: "US"` / `*.traeapi.us`) is recognized but not served yet**: a US credential is never routed to the Singapore gateways; the account panel names the account and says the region is unsupported, and that signing in again changes nothing (issue #66).
 - **Region-isolated directories and selections** — CN and international each keep their own model directory, enabled picks, image opt-ins, and context budgets, and each provider reads only its own slot.
 - **Vision follows Trae's own declaration** — when Trae marks a model `multimodal`, the plugin advertises it as such with no manual tick per model (issue #16). The rule is "**models you tick ∪ models Trae marks multimodal**": models Trae marks `false`, or does not mark at all, stay text-only and can still be turned on by hand. A row enabled automatically is shown ticked and read-only, with the reason. See "Image input" below.
 - **Account switching** — refreshes the token list and lets users select an account without storing tokens in DSH settings. **Your choice is remembered and stays in effect**: the plugin will never switch accounts on its own just because the bound one ran out of credit or another usable one was found (switching bills a different person). So when the bound account is exhausted the card **says so explicitly** and lists the other accounts on this machine that still have credit, with their balances, for you to switch to in one click — instead of showing an empty panel or quietly rebinding you. "Refresh accounts & tokens" now always reports what happened (how many accounts were found, who is still bound) instead of appearing to do nothing. The dropdown names the product (`Trae` / `TRAE SOLO` / international) so a credential left behind by an uninstalled app is recognisable.

package/README.md

@@ -47,7 +47,7 @@
 - **活动优惠徽标** —— Trae 把促销规则发在目录里（`activity_discount`：折扣比例、原价、闲时时段与时区），插件按**当前时钟**判定后，在模型名旁边画一枚胶囊：`5 折` / `闲时 5 折` / `限时 5 折`，悬停写明原价、现价与时段。判定放在**渲染时刻**而不是解析时刻，所以夜间折扣不会在第二天早上继续挂着；上游说「此刻没打折」就不画，**不从倍率反推**，也不给没有结束时间的活动编「限时」。这是纯提示：不改请求、不改计费，国际区（订阅制）没有这项数据因此不显示。详见 [docs/PROMO_BADGE.md](docs/PROMO_BADGE.md)。**同一枚胶囊也画在 DSH 的模型选择器里**（宿主 `conversation.input.model.label` 插槽），挑模型时就能看见——毕竟徽标画在设置卡片里时，你已经选完了。选择器里**倍率只出现一次**：名字里已有的目录倍率会被拆出来，有折扣时换成**折后价**（与卡片同一套时钟判定，同一份数据），打开选择器不会额外触发上游读。
 - **DSH 本地工具循环** —— 通过 Trae `llm_utils_chat` 获取待执行的结构化 `tool_calls`，交由 DSH 自带的本地工具执行，再将工具结果回传模型。
 - **文生图（`trae_draw_image`）** —— 把登录账号的 Trae 文生图能力接进会话：模型画一张图，插件把**图片字节一起取回来**、写进会话目录再显示给你。**默认关闭、按面板单独开**——生图真实消耗积分（实测 CN 个人版 `1920x1920` 一张约 8.8），所以它和识图那种「让不让看图」的开关不同，只能由你点头。协议、尺寸边界、取图那两步，以及为什么「取图」那条 GET 其实是又一次生成，见下方「[文生图](#文生图trae_draw_image)」。
-- **国内国际双区域自动识别** —— 自动发现 Trae CN / TRAE SOLO CN / Trae / TRAE SOLO 四个本地安装的登录账号；区域由凭证自带的 `userRegion` 声明自动判定（host 后缀与 edition 标签兜底），无需手动指定。
+- **国内国际双区域自动识别** —— 自动发现 Trae CN / TRAE SOLO CN / Trae / TRAE SOLO 四个本地安装的登录账号；区域由凭证自带的 `userRegion` 声明自动判定（host 后缀与 edition 标签兜底），无需手动指定。**美国区（`userRegion: "US"` / `*.traeapi.us`）目前「识别但不接入」**：插件不会把 US 凭据当成新加坡区发出去，而会在账号面板明确写「美国区（US）暂不支持」并点名账号，同时说明重新登录不会改变结果（issue #66）。
 - **目录与勾选按面板隔离** —— 三个面板各一套模型目录、勾选、图片开关与上下文预算，各自读各自的槽位。名录从**该面板所钉的那条网关**读取——原本钉在企业池的客户端去读消费池名录，会永远发现不了自己池的独占模型。
 - **识图能力跟随 Trae 自身的标注** —— Trae 把某个模型标为 `multimodal` 时，插件直接按多模态对外声明，无需你在卡片上逐一手勾（issue #16）。判据是「**你手动勾选的 ∪ Trae 标注多模态的**」：Trae 明确标 `false` 或未标注的模型保持纯文本，你可以照旧手动为它们打开图片输入。卡片上被自动开启的那一行显示为已勾选且只读，并说明原因。详见下方「图片输入（识图）」。
 - **多账号切换** —— 支持重新读取 Token 列表并选择账号；Token 不写入 DSH 设置。**你的选择会被记住并长期生效**：插件不会因为某个账号额度用尽、或检测到另一个可用账号就自作主张替你切换（换账号意味着换人计费）——唯一的例外是你**亲自打开**的账号池（见下一条），那是一个显式选择，而不是插件的自作主张。所以当绑定的账号额度耗尽时，卡片会**明确告诉你**，并把本机其他还有额度的账号连同其可用积分数列出来，由你一键切换——而不是让面板一直空着、也不自动把你切走。「刷新账号与 Token」每次都会回报结果（找到几个账号、当前仍绑定谁），不会再「点了没反应」。下拉里显示的是产品名（`Trae` / `TRAE SOLO` / 国际版），便于分辨凭据来自哪个安装。

package/lib/client.js

@@ -3905,6 +3905,22 @@ window.__ModuleLoader__.load({
 		* Structure, CSS classes, and button primitives mirror `dsh-subagent-default-model`'s
 		* `SubagentModelCard` so the two plugins share one external-presentation language.
 		*/
+		/**
+		* Failure text of a route: the server's own message when it sent one, else the
+		* bare status.
+		*
+		* Issue #66: the card used to throw `HTTP ${status}` and drop the body, so the
+		* Host's explanation ("SOLO remote models returned HTTP 401", or the US-region
+		* verdict) never reached the user. A 401 from the wrong gateway and a plugin
+		* crash therefore read identically.
+		*/
+		function routeErrorText(body, status) {
+			if (typeof body === "object" && body !== null) {
+				const error = body.error;
+				if (typeof error === "string" && error.trim() !== "") return error;
+			}
+			return `HTTP ${status}`;
+		}
 		const POLL_INTERVAL_MS = 6e4;
 		const TRAE_GITHUB_URL = "https://github.com/dingminhua/dsh-connect-trae";
 		/**
@@ -4412,7 +4428,7 @@ window.__ModuleLoader__.load({
 						...signal === void 0 ? {} : { signal }
 					});
 					const value = await response.json().catch(() => void 0);
-					if (!response.ok) throw new Error(`HTTP ${response.status}`);
+					if (!response.ok) throw new Error(routeErrorText(value, response.status));
 					const usage = value;
 					if (mounted.current && signal?.aborted !== true) setStatusByRegion((prev) => ({
 						...prev,
@@ -4545,8 +4561,8 @@ window.__ModuleLoader__.load({
 						headers: { accept: "application/json" },
 						credentials: "same-origin"
 					});
-					const body = await response.json();
-					if (!response.ok || !Array.isArray(body.accounts)) throw new Error(`HTTP ${response.status}`);
+					const body = await response.json().catch(() => void 0);
+					if (!response.ok || body === void 0 || !Array.isArray(body.accounts)) throw new Error(routeErrorText(body, response.status));
 					/**
 					* What this press must persist, and why it is NOT `accounts.find(selected)`.
 					*
@@ -4891,8 +4907,8 @@ window.__ModuleLoader__.load({
 						headers: { accept: "application/json" },
 						credentials: "same-origin"
 					});
-					const body = await response.json();
-					if (!response.ok || !Array.isArray(body.models)) throw new Error(`HTTP ${response.status}`);
+					const body = await response.json().catch(() => void 0);
+					if (!response.ok || body === void 0 || !Array.isArray(body.models)) throw new Error(routeErrorText(body, response.status));
 					const fresh = body.models;
 					const freshIds = new Set(fresh.map((model) => model.id));
 					const stillEnabled = [...activeEnabledIds].filter((id) => freshIds.has(id));
@@ -5907,6 +5923,20 @@ window.__ModuleLoader__.load({
 													children: activeRegion === "cn" ? t("row.tabCn") : activeRegion === "enterprise" ? t("row.tabEnterprise") : t("row.tabAi")
 												})]
 											}),
+											status.unsupportedRegion === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+												className: "dsm-trae-diag-row",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "dsm-trae-diag-label",
+													children: t("row.diagUnsupportedRegion")
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+													className: "dsm-trae-diag-value dsm-trae-diag-bad",
+													children: [
+														status.unsupportedRegion.region.toUpperCase(),
+														" · ",
+														status.unsupportedRegion.accounts.join(", ")
+													]
+												})]
+											}),
 											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 												className: "dsm-trae-diag-row",
 												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -6046,6 +6076,21 @@ window.__ModuleLoader__.load({
 										className: "dsm-trae-usage-text",
 										children: status.message ?? t("row.signedOutHint")
 									}),
+									status.unsupportedRegion === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("details", {
+										className: "dsm-trae-quarantine",
+										open: true,
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("summary", { children: t("row.unsupportedRegionTitle") }),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+												className: "dsm-trae-quarantine-hint",
+												children: t("row.unsupportedRegionHint")
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+												className: "dsm-trae-quarantine-list",
+												children: status.unsupportedRegion.accounts.map((name) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: name }) }, name))
+											})
+										]
+									}),
 									status.quarantined && status.quarantined.length > 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("details", {
 										className: "dsm-trae-quarantine",
 										open: true,
@@ -6843,6 +6888,9 @@ window.__ModuleLoader__.load({
 			"row.settingsWriteFailed": "The setting was not saved: {message}",
 			"row.signedOut": "Not signed in",
 			"row.signedOutHint": "Sign in once in the Trae desktop app; this plugin follows that sign-in automatically.",
+			"row.unsupportedRegionTitle": "US region is not supported yet",
+			"row.unsupportedRegionHint": "A Trae account on this machine belongs to the United States region (userRegion \"US\" / host *.traeapi.us). This build does not serve that region, so the account is NOT used and no request is sent to the Singapore gateway — signing in again changes nothing. Use a CN or Singapore account (or the Trae CN build) in this panel.",
+			"row.diagUnsupportedRegion": "Unsupported region",
 			"row.searchedTitle": "Paths checked",
 			"row.searchedHint": "No sign-in was found. These locations were probed; if your Trae stores its login elsewhere, please report the path.",
 			"row.searchedMore": "Show {count} more",
@@ -7227,6 +7275,9 @@ window.__ModuleLoader__.load({
 			"row.settingsWriteFailed": "设置未能保存：{message}",
 			"row.signedOut": "未登录",
 			"row.signedOutHint": "在 Trae 桌面 App 里登录一次即可，插件会自动跟随当前登录的账号。",
+			"row.unsupportedRegionTitle": "美国区（US）暂不支持",
+			"row.unsupportedRegionHint": "本机有一个 Trae 账号属于美国区（userRegion \"US\" / 主机 *.traeapi.us）。本版本尚未支持该区，因此不会使用这个账号，也不会把请求发往新加坡网关——重新登录不会有任何变化。请在该面板改用国内版或新加坡区账号（或使用 Trae 国内版客户端）。",
+			"row.diagUnsupportedRegion": "未支持的区域",
 			"row.searchedTitle": "已检查的路径",
 			"row.searchedHint": "未找到登录信息。以下是插件探测过的位置；如果你的 Trae 把登录信息存在别处，请把该路径反馈给我们。",
 			"row.searchedMore": "展开其余 {count} 条",

package/lib/index.d.ts

@@ -142,6 +142,23 @@ declare function traeStorageCandidates(platform?: NodeJS.Platform, home?: string
 //#region src/region.d.ts
 /** Storage/routing bucket: the CN service or the international (ai) service. */
 type TraeRegion = 'cn' | 'ai';
+/**
+ * The service a credential's own claims name.
+ *
+ * WIDER than {@link TraeRegion} on purpose. The US cluster is a real,
+ * distinguishable Trae service — `userRegion: "US"` and hosts under
+ * `*.traeapi.us` (issue #66, measured on an international 3.6.4 install:
+ * `grow-normal.traeapi.us` answers the pay endpoint with 200 where the SG
+ * gateway answers 401) — but this plugin does not serve it yet.
+ *
+ * Naming it as its own value is the whole fix: while the US claim was
+ * unrecognised, `regionOfCredential` fell through to the edition label (`sg` →
+ * `ai`) and shipped a US token to `*.trae.ai`, where every read answered 401
+ * and the card reported it as a generic "refresh failed". A value the type
+ * system carries forces every gateway site to say out loud what it does with a
+ * region it cannot serve, instead of silently inheriting the SG routing.
+ */
+type TraeServiceRegion = 'cn' | 'ai' | 'us';
 /**
  * One section of the plugin card: a provider the user can switch, bind an
  * account to, and pick models for, INDEPENDENTLY.
@@ -188,20 +205,36 @@ declare function regionOfEdition(edition: TraeEdition): TraeRegion;
  * Region from the credential's `userRegion` claim. The desktop storage spells
  * it as an object (`{"region":"CN","_aiRegion":"CN"}`); the app logs also
  * spell the bare value lowercase (`"sg"`). Both are accepted, case-blind.
+ *
+ * `"US"` is recognized as its own region (issue #66). It used to fall through
+ * this function unrecognised, which is what let a US credential inherit the SG
+ * routing from the edition label.
+ */
+declare function regionOfUserRegion(value: unknown): TraeServiceRegion | undefined;
+/**
+ * Region from a credential host (`.trae.ai` → ai, `.trae.cn`/`.trae.com.cn` →
+ * cn, `.traeapi.us` → us).
+ *
+ * The US suffix is checked explicitly. It is NOT a special case of
+ * `.trae.ai`: `grow-normal.traeapi.us` is a different cluster with its own
+ * pay/pay-status endpoints, and the plugin's SG gateways answer a US token
+ * with 401 (issue #66).
  */
-declare function regionOfUserRegion(value: unknown): TraeRegion | undefined;
-/** Region from a credential host (`.trae.ai` → ai, `.trae.cn`/`.trae.com.cn` → cn). */
-declare function regionOfHost(host: string | undefined): TraeRegion | undefined;
+declare function regionOfHost(host: string | undefined): TraeServiceRegion | undefined;
 /**
  * Region of a credential: the `userRegion` claim wins, the host suffix is the
  * fallback, and the edition label is the last resort. Every level is derived
  * from data the credential itself carries, so no user configuration is needed.
+ *
+ * The edition fallback is only ever reached by a credential that carries
+ * NEITHER a claim NOR a resolvable host (a CLI token). That matters: it is the
+ * reason a US credential no longer becomes `ai` — its own claim resolves first.
  */
 declare function regionOfCredential(credential: {
   edition: TraeEdition;
   host?: string;
   userRegion?: string;
-}): TraeRegion;
+}): TraeServiceRegion;
 //#endregion
 //#region src/catalog.d.ts
 type TraeInputModality = 'text' | 'image';
@@ -1266,6 +1299,20 @@ interface TraeWebPayStatus {
     maxUsage: number;
   };
 }
+/**
+ * A credential on this machine that names a region this build cannot serve yet
+ * (issue #66: the US cluster).
+ *
+ * Carried on BOTH shapes: the panel that shows it is normally signed OUT —
+ * the credential is deliberately excluded from billing — so the signed-out
+ * document is the only place the user can learn that a real sign-in is sitting
+ * on disk and why it is not being used.
+ */
+interface TraeWebUnsupportedRegion {
+  region: 'us';
+  /** Display names of the credentials carrying that claim; never token material. */
+  accounts: readonly string[];
+}
 /** The JSON document the plugin card renders. */
 type TraeWebUsage = {
   status: 'signed-out';
@@ -1278,6 +1325,8 @@ type TraeWebUsage = {
    * after a lost copy, so that is where the notice has to be.
    */
   quarantined?: readonly TraeWebQuarantine[];
+  /** A recognized-but-unserved region on this machine (issue #66). */
+  unsupportedRegion?: TraeWebUnsupportedRegion;
   enabled?: boolean;
 } | {
   status: 'signed-in';
@@ -1338,6 +1387,12 @@ type TraeWebUsage = {
   /** Subscription status of an international account (region ai only). */
   payStatus?: TraeWebPayStatus;
   payStatusError?: string;
+  /**
+   * A recognized-but-unserved region on this machine (issue #66). Present
+   * alongside a working account when the machine also holds e.g. a US
+   * login — that account is not billed, but the panel still says so.
+   */
+  unsupportedRegion?: TraeWebUnsupportedRegion;
   /**
    * This panel's account-pool state, when the Host build supports it.
    *
@@ -1830,6 +1885,19 @@ interface TraeAccountChoice {
   refreshExpiresAtMs?: number;
   selected: boolean;
 }
+/**
+ * A credential on this machine that names a region this build cannot serve yet
+ * (issue #66: the US cluster).
+ *
+ * Reported so the card can explain a signed-out panel that a user knows is
+ * signed in. It is never selectable and never billed: `readAll()` skips these,
+ * so they cannot reach a gateway at all.
+ */
+interface TraeUnsupportedCredential {
+  region: Exclude<TraeServiceRegion, TraeRegion>;
+  /** Display identity of the credential — never token material. */
+  accountName: string;
+}
 /**
  * Why one candidate path did not yield an account. These are safe to surface:
  * they carry paths and error text, never token material.
@@ -2186,6 +2254,22 @@ declare class TraeCredentialStore {
     expiresAtMs?: number;
     source?: TraeCredential['source'];
   }>;
+  /**
+   * Credentials this machine holds for a region this build cannot serve yet.
+   *
+   * Issue #66: a US credential used to resolve to `ai`, so the panel billed it
+   * against the SG gateway and every read answered 401. Now it is excluded from
+   * resolution (see `readAll`), which would leave the panel saying "not signed
+   * in" on a machine the user knows IS signed in — so the exclusion has to be
+   * explainable. This reads exactly the credentials `readAll` refuses to
+   * RESOLVE and reports their display identity; nothing here is selectable,
+   * billable, or sent anywhere.
+   *
+   * Scoped to the international bucket: a US install is an international
+   * install, so only the `ai` panel (and an unscoped diagnostic store) can be
+   * the one missing an account because of it.
+   */
+  unsupportedCredentials(): Promise<TraeUnsupportedCredential[]>;
   desktopFilePresent(): Promise<boolean>;
   /**
    * Remove every plugin-owned copy this store could read (per-region file,
@@ -3342,6 +3426,29 @@ type TraeStreamEvent = {
    */
   cacheReadTokens?: number;
   cacheWriteTokens?: number;
+} | {
+  /**
+   * The upstream's own account of how the request was served: `metadata`
+   * (acceptance, plus `prompt_cache_pool_record`) and `timing_cost` (the
+   * pipeline and the backing provider model).
+   *
+   * These events were previously folded into `unknown` and dropped. That
+   * mattered for issue #67: `prompt_cache_pool_record` is the ONLY upstream
+   * signal that says whether a prompt-cache pool was even attached to the
+   * request, so with it dropped a "0% cache" report could not be told apart
+   * from a plugin that lost the numbers. See docs/ISSUE67_DIAGNOSIS.md.
+   */
+  type: 'diagnostic';
+  /**
+   * `metadata.prompt_cache_pool_record`. `null` is a real, observed value
+   * (100% of measured requests on 2026-10-28) and means the upstream attached
+   * no cache pool; it is kept distinct from "the field was absent".
+   */
+  promptCachePoolRecord?: unknown;
+  /** `timing_cost.name`, e.g. `llm_raw_chat_v2`. */
+  pipeline?: string;
+  /** `timing_cost.provider_model_name` — the model that actually answered. */
+  providerModelName?: string;
 } | {
   type: 'done';
   finishReason: string;
@@ -3485,7 +3592,21 @@ declare class TraeSoloBridge implements TraeUpstreamClient {
   private readonly upstream;
   private readonly catalog?;
   private readonly wireResolver?;
-  constructor(upstream: TraeUpstreamClient, catalog?: Pick<TraeCatalog, "current"> | undefined, wireResolver?: TraeWireResolver | undefined);
+  /**
+   * Optional sink for the upstream's own diagnostics (`metadata` /
+   * `timing_cost`). Issue #67: without it, `prompt_cache_pool_record: null`
+   * was invisible, so "the upstream attached no cache pool" and "the plugin
+   * lost the numbers" looked identical to a user reading a 0% cache rate.
+   */
+  private readonly log?;
+  constructor(upstream: TraeUpstreamClient, catalog?: Pick<TraeCatalog, "current"> | undefined, wireResolver?: TraeWireResolver | undefined,
+  /**
+   * Optional sink for the upstream's own diagnostics (`metadata` /
+   * `timing_cost`). Issue #67: without it, `prompt_cache_pool_record: null`
+   * was invisible, so "the upstream attached no cache pool" and "the plugin
+   * lost the numbers" looked identical to a user reading a 0% cache rate.
+   */
+  log?: ((message: string, detail?: unknown) => void) | undefined);
   chatStream(bodyJson: string, signal?: AbortSignal): Promise<TraeChatResult>;
 }
 //#endregion
@@ -3875,7 +3996,13 @@ declare class TraeUsageClient {
   private readonly baseUrl;
   private readonly timeoutMs;
   constructor(options: TraeUsageOptions);
-  /** Region of the current credential; `cn` when unresolvable. */
+  /**
+   * Region of the current credential; `cn` when unresolvable.
+   *
+   * A US credential throws {@link TraeUnsupportedRegionError} instead of being
+   * rounded to the international bucket — issue #66: the rounding is what sent
+   * a US token to the SG pay gateway, where the answer is 401.
+   */
   private currentRegion;
   /**
    * Pay base for the current credential's region. An explicit baseUrl (tests,

package/lib/index.js

@@ -1154,6 +1154,31 @@ function createTraeAdapter(options) {
 }
 //#endregion
 //#region src/region.ts
+/**
+* Code the Host reports for a region this build recognises but cannot serve.
+* The card and any external caller can switch on it; the message is only for
+* humans.
+*/
+const TRAE_UNSUPPORTED_REGION_CODE = "unsupported-region";
+/** Message for a US credential, phrased to end the re-login loop. */
+const TRAE_UNSUPPORTED_REGION_MESSAGE = "This Trae account belongs to the United States region (userRegion \"US\", host *.traeapi.us), which dsh-connect-trae does not support yet. Requests are NOT sent to the Singapore gateway; sign in with a CN or Singapore account (or use the CN build of Trae) to use this panel.";
+/**
+* A credential that resolved to a region this build does not serve.
+*
+* Thrown BEFORE any request is built, by every client that reads a credential:
+* the failure has to be a local, explicit verdict, not a 401 from the wrong
+* gateway (issue #66: a US token sent to `*.trae.ai` answers 401, which read as
+* "your sign-in expired" and produced an endless re-login loop).
+*/
+var TraeUnsupportedRegionError = class extends Error {
+	region;
+	name = "TraeUnsupportedRegionError";
+	code = TRAE_UNSUPPORTED_REGION_CODE;
+	constructor(region) {
+		super(TRAE_UNSUPPORTED_REGION_MESSAGE);
+		this.region = region;
+	}
+};
 /** Every panel, in card tab order. */
 const TRAE_PANELS = [
 	"cn",
@@ -1223,6 +1248,10 @@ function regionOfEdition(edition) {
 * Region from the credential's `userRegion` claim. The desktop storage spells
 * it as an object (`{"region":"CN","_aiRegion":"CN"}`); the app logs also
 * spell the bare value lowercase (`"sg"`). Both are accepted, case-blind.
+*
+* `"US"` is recognized as its own region (issue #66). It used to fall through
+* this function unrecognised, which is what let a US credential inherit the SG
+* routing from the edition label.
 */
 function regionOfUserRegion(value) {
 	const raw = typeof value === "object" && value !== null && !Array.isArray(value) ? value["region"] : value;
@@ -1230,8 +1259,17 @@ function regionOfUserRegion(value) {
 	const lowered = raw.trim().toLowerCase();
 	if (lowered === "cn") return "cn";
 	if (lowered === "sg" || lowered === "ai") return "ai";
+	if (lowered === "us") return "us";
 }
-/** Region from a credential host (`.trae.ai` → ai, `.trae.cn`/`.trae.com.cn` → cn). */
+/**
+* Region from a credential host (`.trae.ai` → ai, `.trae.cn`/`.trae.com.cn` →
+* cn, `.traeapi.us` → us).
+*
+* The US suffix is checked explicitly. It is NOT a special case of
+* `.trae.ai`: `grow-normal.traeapi.us` is a different cluster with its own
+* pay/pay-status endpoints, and the plugin's SG gateways answer a US token
+* with 401 (issue #66).
+*/
 function regionOfHost(host) {
 	if (host === void 0) return void 0;
 	const trimmed = host.trim();
@@ -1242,6 +1280,7 @@ function regionOfHost(host) {
 	} catch {
 		return;
 	}
+	if (hostname === "traeapi.us" || hostname.endsWith(".traeapi.us")) return "us";
 	if (hostname === "trae.ai" || hostname.endsWith(".trae.ai")) return "ai";
 	if (hostname === "trae.cn" || hostname.endsWith(".trae.cn") || hostname.endsWith(".trae.com.cn")) return "cn";
 }
@@ -1249,10 +1288,32 @@ function regionOfHost(host) {
 * Region of a credential: the `userRegion` claim wins, the host suffix is the
 * fallback, and the edition label is the last resort. Every level is derived
 * from data the credential itself carries, so no user configuration is needed.
+*
+* The edition fallback is only ever reached by a credential that carries
+* NEITHER a claim NOR a resolvable host (a CLI token). That matters: it is the
+* reason a US credential no longer becomes `ai` — its own claim resolves first.
 */
 function regionOfCredential(credential) {
 	return regionOfUserRegion(credential.userRegion) ?? regionOfHost(credential.host) ?? regionOfEdition(credential.edition);
 }
+/** Whether this build actually serves the region (only `cn` and `ai` today). */
+function isSupportedRegion(region) {
+	return region !== "us";
+}
+/**
+* Narrow a resolved credential region to a servable bucket, or throw
+* {@link TraeUnsupportedRegionError}.
+*
+* Every gateway lookup goes through this instead of indexing
+* `REGION_GATEWAYS`/`TRAE_REMOTE_DIRECTORY_FUNCTIONS` directly: those maps hold
+* only the two supported clusters, and the missing index IS the bug in issue
+* #66 (`REGION_GATEWAYS[regionOfCredential(us)]` silently read the `ai` entry,
+* because the resolver had already rounded the US claim down to SG).
+*/
+function assertSupportedRegion(region) {
+	if (!isSupportedRegion(region)) throw new TraeUnsupportedRegionError(region);
+	return region;
+}
 //#endregion
 //#region src/status-paths.ts
 /** Plugin-owned usage endpoint consumed by its browser half. */
@@ -2839,7 +2900,7 @@ var TraeCredentialStore = class {
 			accountName: credential.accountName ?? (credential.userId || `${credential.edition} account`),
 			edition: credential.edition,
 			enterprise: isEnterpriseAccount(credential),
-			region: regionOfCredential(credential),
+			region: assertSupportedRegion(regionOfCredential(credential)),
 			source: "dsh",
 			tokenExpiresAtMs: credential.expiresAtMs,
 			...credential.refreshExpiresAtMs === void 0 ? {} : { refreshExpiresAtMs: credential.refreshExpiresAtMs },
@@ -3042,7 +3103,11 @@ var TraeCredentialStore = class {
 	}
 	async resolve() {
 		const credential = await this.current();
-		if (credential === void 0) throw new Error(`trae: no signed-in account found (${this.candidates().map((item) => item.path).join(" or ")})`);
+		if (credential === void 0) {
+			const first = (await this.unsupportedCredentials().catch(() => []))[0];
+			if (first !== void 0) throw new TraeUnsupportedRegionError(first.region);
+			throw new Error(`trae: no signed-in account found (${this.candidates().map((item) => item.path).join(" or ")})`);
+		}
 		if (credential.expiresAtMs > Date.now() + this.refreshMarginMs) return credential;
 		this.inflight ??= this.refreshNow(credential).finally(() => {
 			this.inflight = void 0;
@@ -3062,6 +3127,42 @@ var TraeCredentialStore = class {
 			return { state: "signed-out" };
 		}
 	}
+	/**
+	* Credentials this machine holds for a region this build cannot serve yet.
+	*
+	* Issue #66: a US credential used to resolve to `ai`, so the panel billed it
+	* against the SG gateway and every read answered 401. Now it is excluded from
+	* resolution (see `readAll`), which would leave the panel saying "not signed
+	* in" on a machine the user knows IS signed in — so the exclusion has to be
+	* explainable. This reads exactly the credentials `readAll` refuses to
+	* RESOLVE and reports their display identity; nothing here is selectable,
+	* billable, or sent anywhere.
+	*
+	* Scoped to the international bucket: a US install is an international
+	* install, so only the `ai` panel (and an unscoped diagnostic store) can be
+	* the one missing an account because of it.
+	*/
+	async unsupportedCredentials() {
+		if (this.region !== void 0 && this.region !== "ai") return [];
+		const found = /* @__PURE__ */ new Map();
+		const consider = (credential) => {
+			const region = regionOfCredential(credential);
+			if (isSupportedRegion(region)) return;
+			const id = traeAccountId(credential);
+			if (found.has(id)) return;
+			found.set(id, {
+				region,
+				accountName: credential.accountName ?? (credential.userId || `${credential.edition} account`)
+			});
+		};
+		try {
+			for (const credential of (await this.readDesktopAll()).credentials) consider(credential);
+		} catch {}
+		try {
+			for (const credential of await this.readOwns()) consider(credential);
+		} catch {}
+		return [...found.values()];
+	}
 	async desktopFilePresent() {
 		for (const candidate of this.candidates()) try {
 			if ((await stat(candidate.path)).isFile()) return true;
@@ -3216,6 +3317,7 @@ var TraeCredentialStore = class {
 		const { credentials: desktop } = await this.readDesktopAll();
 		const byAccount = /* @__PURE__ */ new Map();
 		const consider = (credential) => {
+			if (!isSupportedRegion(regionOfCredential(credential))) return;
 			if (!this.matchesRegion(credential)) return;
 			const id = traeAccountId(credential);
 			const incumbent = byAccount.get(id);
@@ -4608,7 +4710,7 @@ var TraeOfficialRosterClient = class {
 		if (this.failedAt !== void 0 && now - this.failedAt < ROSTER_CACHE_MS) return void 0;
 		try {
 			const [credential, identity] = await Promise.all([this.options.credential(), this.options.identity()]);
-			const region = regionOfCredential(credential);
+			const region = assertSupportedRegion(regionOfCredential(credential));
 			const base = this.options.baseUrl ?? (this.options.route === "enterprise" ? "https://console.enterprise.trae.cn" : REGION_GATEWAYS[region].chat);
 			const response = await this.fetchImpl(traeEndpoint(base, TRAE_MODEL_DETAIL_PATH), {
 				method: "POST",
@@ -5129,7 +5231,7 @@ var TraeSoloUpstreamClient = class {
 	*/
 	async fetchModels(signal) {
 		const [credential, identity] = await Promise.all([this.options.credential(), this.options.identity()]);
-		const region = regionOfCredential(credential);
+		const region = assertSupportedRegion(regionOfCredential(credential));
 		const base = this.options.baseUrl ?? this.chatBaseOf(credential);
 		const headers = {
 			...buildTraeCnHeaders(credential, identity),
@@ -5227,7 +5329,18 @@ var TraeSoloUpstreamClient = class {
 		}
 		const [credential, identity] = await Promise.all([this.options.credential(), this.options.identity()]);
 		const headers = buildTraeCnHeaders(credential, identity);
-		const base = this.options.baseUrl ?? this.chatBaseOf(credential);
+		let base;
+		try {
+			assertSupportedRegion(regionOfCredential(credential));
+			base = this.options.baseUrl ?? this.chatBaseOf(credential);
+		} catch (error) {
+			return {
+				ok: false,
+				status: 503,
+				kind: "unconfigured",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		}
 		if (this.options.route === "enterprise") try {
 			const parsed = JSON.parse(prepared);
 			if (parsed["session_id"] === void 0) parsed["session_id"] = randomUUID();
@@ -5304,7 +5417,7 @@ var TraeSoloUpstreamClient = class {
 	/** Chat gateway for this client's pinned route. */
 	chatBaseOf(credential) {
 		if (this.options.route === "enterprise") return TRAE_ENTERPRISE_HOST;
-		return REGION_GATEWAYS[regionOfCredential(credential)].chat;
+		return REGION_GATEWAYS[assertSupportedRegion(regionOfCredential(credential))].chat;
 	}
 };
 /**
@@ -5468,6 +5581,12 @@ function decodeTraeEvent(event) {
 		...typeof record["cache_read_input_tokens"] === "number" ? { cacheReadTokens: record["cache_read_input_tokens"] } : {},
 		...typeof record["cache_creation_input_tokens"] === "number" ? { cacheWriteTokens: record["cache_creation_input_tokens"] } : {}
 	};
+	if (event.event === "metadata" || event.event === "timing_cost") return {
+		type: "diagnostic",
+		...record["prompt_cache_pool_record"] === void 0 ? {} : { promptCachePoolRecord: record["prompt_cache_pool_record"] },
+		...typeof record["name"] === "string" ? { pipeline: record["name"] } : {},
+		...typeof record["provider_model_name"] === "string" ? { providerModelName: record["provider_model_name"] } : {}
+	};
 	if (event.event === "done" || typeof record["finish_reason"] === "string" && record["response"] === void 0) return {
 		type: "done",
 		finishReason: typeof record["finish_reason"] === "string" ? record["finish_reason"] : "stop"
@@ -5634,7 +5753,7 @@ function bridgeTraeSoloStream(response, model) {
 	return bridgeTraeSource(source, model);
 }
 /** {@link bridgeTraeSoloStream} over an already-opened byte stream. */
-function bridgeTraeSource(source, model) {
+function bridgeTraeSource(source, model, log) {
 	const id = `chatcmpl-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
 	const created = Math.floor(Date.now() / 1e3);
 	const decoder = new TextDecoder();
@@ -5667,6 +5786,15 @@ function bridgeTraeSource(source, model) {
 					if (failure !== void 0) upstreamError = new Error(describeTraeFailure(failure));
 					return;
 				}
+				if (decoded.type === "diagnostic") {
+					if (decoded.promptCachePoolRecord !== void 0 || decoded.pipeline !== void 0) log?.("dsh-connect-trae: upstream request diagnostics", {
+						model,
+						promptCachePoolRecord: decoded.promptCachePoolRecord,
+						pipeline: decoded.pipeline,
+						providerModelName: decoded.providerModelName
+					});
+					return;
+				}
 				if (decoded.type === "delta") {
 					const delta = {};
 					if (decoded.text !== "") delta["content"] = decoded.text;
@@ -5819,7 +5947,7 @@ async function openTraeSource(response) {
 						message: describeTraeFailure(failure)
 					};
 				}
-				if (decoded.type !== "unknown") answered = true;
+				if (decoded.type !== "unknown" && decoded.type !== "diagnostic") answered = true;
 			}
 			if (answered) break;
 		}
@@ -5843,12 +5971,12 @@ async function openTraeSource(response) {
 * The sibling {@link bridgeTraeSoloStream} stays synchronous and always answers
 * 200; it is the primitive, and this is the policy the bridge class uses.
 */
-async function bridgeTraeSoloStreamOrFail(response, model) {
+async function bridgeTraeSoloStreamOrFail(response, model, log) {
 	const opened = await openTraeSource(response);
 	if (!opened.ok) return opened;
 	return {
 		ok: true,
-		response: bridgeTraeSource(opened.source, model)
+		response: bridgeTraeSource(opened.source, model, log)
 	};
 }
 /**
@@ -5889,10 +6017,12 @@ var TraeSoloBridge = class {
 	upstream;
 	catalog;
 	wireResolver;
-	constructor(upstream, catalog, wireResolver) {
+	log;
+	constructor(upstream, catalog, wireResolver, log) {
 		this.upstream = upstream;
 		this.catalog = catalog;
 		this.wireResolver = wireResolver;
+		this.log = log;
 	}
 	async chatStream(bodyJson, signal) {
 		let model = "glm-5.2";
@@ -5980,7 +6110,7 @@ var TraeSoloBridge = class {
 		}
 		const result = await this.upstream.chatStream(prepared, signal);
 		if (!result.ok) return result;
-		return await bridgeTraeSoloStreamOrFail(result.response, model);
+		return await bridgeTraeSoloStreamOrFail(result.response, model, this.log);
 	}
 };
 //#endregion
@@ -6071,6 +6201,72 @@ function parseTraeRemoteModel(value, groupFunction) {
 	};
 }
 //#endregion
+//#region src/failure.ts
+/**
+* Failure classification shared by the Host's HTTP routes.
+*
+* Issue #66: the model-refresh route wrapped EVERY thrown error as HTTP 500.
+* A US credential sent to the Singapore gateway answers `401`, that 401 became
+* `{"error":"SOLO remote models returned HTTP 401"}` under status 500, and the
+* card could only say "HTTP 500" — so a region/routing problem was
+* indistinguishable from a plugin crash, and the user re-signed-in instead of
+* looking at the region.
+*
+* The fix is deliberately narrow: upstream HTTP verdicts and the local
+* "region not served" verdict keep their meaning when they cross the route
+* boundary. Only failures that carry no status of their own stay 500.
+*
+* @module dsh-connect-trae/failure
+*/
+/** Code for an upstream that refused the credential (401 / 403). */
+const TRAE_AUTH_FAILURE_CODE = "authentication";
+/** Code for any other upstream HTTP verdict (4xx/5xx that is not auth). */
+const TRAE_UPSTREAM_FAILURE_CODE = "upstream";
+/**
+* A non-2xx answer from a Trae gateway, carrying the status the gateway
+* actually sent.
+*
+* Plain `Error`s are still allowed everywhere (and stay 500 at the route); this
+* class exists so the paths that DO know an upstream status can pass it on
+* instead of leaving it buried in a message string.
+*/
+var TraeHttpError = class extends Error {
+	status;
+	name = "TraeHttpError";
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/**
+* Map a thrown failure onto the Host's HTTP answer.
+*
+*  - a region this build does not serve → `501` + `unsupported-region`
+*    (the request is well-formed; this build simply has no route for it);
+*  - an upstream 401/403 → the SAME status + `authentication`, so the client
+*    can distinguish "sign in again" from "the plugin broke";
+*  - any other upstream status → passed through verbatim + `upstream`;
+*  - anything else (a programming error, a transport failure) → `500`.
+*/
+function httpFailureOf(error) {
+	if (error instanceof TraeUnsupportedRegionError) return {
+		status: 501,
+		code: TRAE_UNSUPPORTED_REGION_CODE
+	};
+	if (error instanceof TraeHttpError) {
+		const status = Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 ? error.status : 502;
+		if (status === 401 || status === 403) return {
+			status,
+			code: TRAE_AUTH_FAILURE_CODE
+		};
+		return {
+			status,
+			code: TRAE_UPSTREAM_FAILURE_CODE
+		};
+	}
+	return { status: 500 };
+}
+//#endregion
 //#region src/solo-remote.ts
 const TRAE_SOLO_REMOTE_BASE = "https://solo.trae.cn/api/remote/v1";
 /**
@@ -6368,7 +6564,7 @@ var TraeSoloRemoteCatalogClient = class TraeSoloRemoteCatalogClient {
 	}
 	async fetchModels(signal) {
 		const credential = await this.options.credential();
-		const region = regionOfCredential(credential);
+		const region = assertSupportedRegion(regionOfCredential(credential));
 		const officialBase = this.baseUrl ?? REGION_GATEWAYS[region].remote;
 		const headers = await this.headers(region);
 		const functions = TRAE_REMOTE_DIRECTORY_FUNCTIONS[region].join(",");
@@ -6388,7 +6584,7 @@ var TraeSoloRemoteCatalogClient = class TraeSoloRemoteCatalogClient {
 				continue;
 			}
 			if (!response.ok) {
-				if (response.status < 500) throw new Error(`SOLO remote models returned HTTP ${response.status}`);
+				if (response.status < 500) throw new TraeHttpError(response.status, `SOLO remote models returned HTTP ${response.status}`);
 				if (base === officialBase) this.officialRetryAtMs = Date.now() + TraeSoloRemoteCatalogClient.OFFICIAL_RETRY_MS;
 				lastError = /* @__PURE__ */ new Error(`SOLO remote models returned HTTP ${response.status}`);
 				continue;
@@ -6729,9 +6925,20 @@ var TraeRawChatUpstreamClient = class {
 			...this.options.config.abVersion === void 0 ? {} : { ab_version: this.options.config.abVersion },
 			pass_back_reasoning: runtime?.passBackReasoning ?? this.options.config.passBackReasoning
 		};
+		let base;
+		try {
+			base = this.options.baseUrl ?? REGION_GATEWAYS[assertSupportedRegion(regionOfCredential(credential))].chat;
+		} catch (error) {
+			return {
+				ok: false,
+				status: 503,
+				kind: "unconfigured",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		}
 		let response;
 		try {
-			response = await this.fetchImpl(traeEndpoint(this.options.baseUrl ?? REGION_GATEWAYS[regionOfCredential(credential)].chat, TRAE_RAW_CHAT_V2_PATH), {
+			response = await this.fetchImpl(traeEndpoint(base, TRAE_RAW_CHAT_V2_PATH), {
 				method: "POST",
 				headers,
 				body: JSON.stringify(body),
@@ -7378,10 +7585,16 @@ var TraeUsageClient = class {
 		this.baseUrl = options.baseUrl;
 		this.timeoutMs = options.timeoutMs ?? 3e4;
 	}
-	/** Region of the current credential; `cn` when unresolvable. */
+	/**
+	* Region of the current credential; `cn` when unresolvable.
+	*
+	* A US credential throws {@link TraeUnsupportedRegionError} instead of being
+	* rounded to the international bucket — issue #66: the rounding is what sent
+	* a US token to the SG pay gateway, where the answer is 401.
+	*/
 	async currentRegion() {
 		const credential = await this.options.credential();
-		return credential === void 0 ? "cn" : regionOfCredential(credential);
+		return credential === void 0 ? "cn" : assertSupportedRegion(regionOfCredential(credential));
 	}
 	/**
 	* Pay base for the current credential's region. An explicit baseUrl (tests,
@@ -7428,7 +7641,7 @@ var TraeUsageClient = class {
 			body: JSON.stringify(data),
 			signal: signal ?? AbortSignal.timeout(this.timeoutMs)
 		});
-		if (!response.ok) throw new Error(`Trae usage endpoint ${path} returned HTTP ${response.status}`);
+		if (!response.ok) throw new TraeHttpError(response.status, `Trae usage endpoint ${path} returned HTTP ${response.status}`);
 		return await response.json();
 	}
 	/**
@@ -7966,7 +8179,9 @@ function previewTransferFile(text) {
 * stack with a credential that belongs to no real CN account. So this helper
 * reuses `regionOfUserRegion` / `regionOfHost` — both of which already return
 * `undefined` on unrecognised input — and deliberately does NOT consult the
-* edition fallback.
+* edition fallback. A US claim (`userRegion: "US"` or a `*.traeapi.us` host)
+* therefore resolves to `us` and matches neither importable region, so that
+* record is skipped like any other foreign one (issue #66).
 */
 function knownRegionOfCredential(credential) {
 	return regionOfUserRegion(credential.userRegion) ?? regionOfHost(credential.host);
@@ -8163,6 +8378,25 @@ function json(res, status, body) {
 	});
 	res.end(payload);
 }
+/**
+* Answer a failed route with the meaning the failure actually has (issue #66).
+*
+* The old rule was `json(res, 500, { error })` everywhere, so a US credential
+* sent to the Singapore gateway surfaced as `HTTP 500
+* {"error":"SOLO remote models returned HTTP 401"}`: the status said "the
+* plugin is broken" while the text said "the gateway refused you". The client
+* could not tell "sign in again" from "this region is unsupported", which is
+* exactly the loop the issue reports. `httpFailureOf` keeps an upstream 401/403
+* as 401/403 and turns the local "not served" verdict into 501 +
+* `unsupported-region`; everything else stays 500.
+*/
+function failJson(res, error) {
+	const failure = httpFailureOf(error);
+	json(res, failure.status, {
+		error: safeMessage(error),
+		...failure.code === void 0 ? {} : { code: failure.code }
+	});
+}
 /** Bound on how many OTHER accounts one status read may probe (issue #25). */
 const TRAE_CREDIT_ALTERNATIVE_LIMIT = 8;
 /**
@@ -8413,6 +8647,21 @@ async function traeWebUsage(deps, panel, options = {}) {
 	* it reads nothing but file names and sizes.
 	*/
 	const quarantined = await Promise.resolve().then(() => store.quarantinedCopies()).catch(() => []);
+	/**
+	* A region this build recognizes but does not serve (issue #66).
+	*
+	* Read ONCE per document and never allowed to fail it: this is a notice about
+	* the user's disk, and the panel it explains is usually the one that has just
+	* been excluded from billing. It is also why the panel can say "a US account
+	* is here, and it is not being used" instead of an undiagnosable "not signed
+	* in" on a machine the user knows is signed in.
+	*/
+	const unsupported = await Promise.resolve().then(() => store.unsupportedCredentials()).catch(() => []);
+	const firstUnsupported = unsupported[0];
+	const unsupportedRegion = firstUnsupported === void 0 ? void 0 : {
+		region: firstUnsupported.region,
+		accounts: unsupported.map((item) => item.accountName)
+	};
 	if ((await store.status()).state !== "signed-in") {
 		const { failures } = await store.diagnose();
 		return {
@@ -8420,6 +8669,7 @@ async function traeWebUsage(deps, panel, options = {}) {
 			accounts,
 			enabled,
 			quarantined,
+			...unsupportedRegion === void 0 ? {} : { unsupportedRegion },
 			searched: failures.map((failure) => ({
 				path: failure.path,
 				edition: failure.edition,
@@ -8434,12 +8684,14 @@ async function traeWebUsage(deps, panel, options = {}) {
 		credential = fast ? await store.current() : await store.resolve();
 		if (credential === void 0) credential = await store.resolve();
 	} catch (error) {
+		const explained = error instanceof TraeUnsupportedRegionError && unsupportedRegion !== void 0;
 		return {
 			status: "signed-out",
 			accounts,
 			enabled,
 			quarantined,
-			message: safeMessage(error)
+			...unsupportedRegion === void 0 ? {} : { unsupportedRegion },
+			...explained ? {} : { message: safeMessage(error) }
 		};
 	}
 	const account = {
@@ -8449,6 +8701,7 @@ async function traeWebUsage(deps, panel, options = {}) {
 		...credential.refreshExpiresAtMs === void 0 ? {} : { refreshExpiresAtMs: credential.refreshExpiresAtMs },
 		region: regionOfPanel(panel),
 		enabled,
+		...unsupportedRegion === void 0 ? {} : { unsupportedRegion },
 		accounts,
 		models: deps.displayModels(panel).map((model) => ({
 			...model,
@@ -8809,7 +9062,7 @@ function registerTraeUsageRoute(ctx, deps) {
 				try {
 					json(res, 200, await traeWebUsage(deps, panel, { detail }));
 				} catch (error) {
-					json(res, 500, { error: safeMessage(error) });
+					failJson(res, error);
 				}
 			}
 		});
@@ -8830,7 +9083,7 @@ function registerTraeUsageRoute(ctx, deps) {
 				try {
 					json(res, 200, { accounts: await traeAccountCredits(deps, panel) });
 				} catch (error) {
-					json(res, 500, { error: safeMessage(error) });
+					failJson(res, error);
 				}
 			}
 		});
@@ -8857,7 +9110,7 @@ function registerTraeUsageRoute(ctx, deps) {
 					if (state === void 0) return json(res, 404, { error: "unknown account" });
 					json(res, 200, state);
 				} catch (error) {
-					json(res, 500, { error: safeMessage(error) });
+					failJson(res, error);
 				}
 			}
 		});
@@ -8949,7 +9202,7 @@ function registerTraeUsageRoute(ctx, deps) {
 				try {
 					json(res, 200, { models: await deps.discoverModels(panel) });
 				} catch (error) {
-					json(res, 500, { error: safeMessage(error) });
+					failJson(res, error);
 				}
 			}
 		});
@@ -8983,7 +9236,7 @@ function registerTraeUsageRoute(ctx, deps) {
 				try {
 					json(res, 200, await deps.probeModels(panel, ids));
 				} catch (error) {
-					json(res, 500, { error: safeMessage(error) });
+					failJson(res, error);
 				}
 			}
 		});
@@ -9067,7 +9320,7 @@ function registerTraeUsageRoute(ctx, deps) {
 						checkin: toCheckin(checkin)
 					});
 				} catch (error) {
-					json(res, 500, { error: safeMessage(error) });
+					failJson(res, error);
 				}
 			}
 		});
@@ -9160,7 +9413,7 @@ function registerTraeUsageRoute(ctx, deps) {
 					try {
 						json(res, 200, { rows: (await pool.checkin(panel)).map((row) => poolCheckinRowViewOf(row)) });
 					} catch (error) {
-						json(res, 500, { error: safeMessage(error) });
+						failJson(res, error);
 					}
 					return;
 				}
@@ -9185,7 +9438,7 @@ function registerTraeUsageRoute(ctx, deps) {
 					if (row === void 0) return json(res, 404, { error: "unknown account" });
 					return json(res, 200, { rows: [poolTestRowViewOf(row)] });
 				} catch (error) {
-					return json(res, 500, { error: safeMessage(error) });
+					return failJson(res, error);
 				}
 				res.writeHead(200, {
 					"Content-Type": "application/x-ndjson",
@@ -10953,7 +11206,7 @@ function apply(ctx, config) {
 				route,
 				log: (message, detail) => ctx.logger.warn(message, detail)
 			});
-			const delegating = new TraeDelegatingUpstreamClient(new TraeSoloBridge(client, catalog, wireResolver));
+			const delegating = new TraeDelegatingUpstreamClient(new TraeSoloBridge(client, catalog, wireResolver, (message, detail) => ctx.logger.warn(message, detail)));
 			routeClients[provider] = {
 				provider,
 				route,
@@ -10994,7 +11247,7 @@ function apply(ctx, config) {
 							runtime: resolved.runtime
 						}
 					}),
-					solo: new TraeSoloBridge(primary.client, catalog, wireResolver),
+					solo: new TraeSoloBridge(primary.client, catalog, wireResolver, (message, detail) => ctx.logger.warn(message, detail)),
 					endpoint: `${REGION_GATEWAYS.cn.chat}/api/ide/v2/llm_raw_chat`,
 					edition: resolved.identity.edition,
 					identity: {
@@ -11391,7 +11644,7 @@ function apply(ctx, config) {
 				identity: () => stack.identity(),
 				route: stack.routeOf(providerOfPanel(panel)),
 				log: (message, detail) => ctx.logger.warn(message, detail)
-			}), stack.catalog, stack.wireResolver)
+			}), stack.catalog, stack.wireResolver, (message, detail) => ctx.logger.warn(message, detail))
 		};
 	}
 	/**
@@ -11473,7 +11726,7 @@ function apply(ctx, config) {
 				identity: () => stack.identity(),
 				route: stack.routeOf(providerOfPanel(panel)),
 				log: (message, detail) => ctx.logger.warn(message, detail)
-			}), stack.catalog, stack.wireResolver);
+			}), stack.catalog, stack.wireResolver, (message, detail) => ctx.logger.warn(message, detail));
 			const chat = (body, signal) => bridge.chatStream(body, signal);
 			bridges.set(accountId, chat);
 			return chat;

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-trae",
   "displayName": "DSH Connect Trae",
   "description": "把本机登录的 Trae 模型接入 DeepSeek Harness：国内版与国际版双供应商并行，提供用量/积分概览与每日签到领取。",
-  "version": "4.6.2",
+  "version": "4.6.4",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",