dsh-subusage 0.11.0 → 0.11.2

package/lib/index.js

@@ -11,6 +11,7 @@ import { MimoLogin } from "./mimo-login.js";
 import { parseVolcAgentPlan, parseVolcCodingPlan, parseVolcSeatAfp, parseVolcSeatCoding, parseVolcSeatIds, volcError, volcSignature } from "./volcengine.js";
 
 const name = "dsh-subusage";
+const VERSION = "0.11.2";
 const inject = ["llm"];
 const PROVIDERS = {
  "zai-coding-cn": { label: "Z.ai", envName: "ZAI_CODING_CN_API_KEY" },
@@ -41,7 +42,7 @@ const PROVIDERS = {
  // 否则选中方舟模型时药丸不会出现。额度读取走管控面 OpenAPI，凭据是 IAM 的 AK/SK 配对
  // （HMAC-SHA256 签名），与这些路由的推理 API Key 是两套：拿推理 Key 去查额度会被上游拒绝
  // （"GetAFPUsage requires Volcengine Ark SSO STS"）。
- // 7 条 volc 路由共用一组 AK/SK（settings.volc）：个人版各自固定一个 Action，
+ // 4 条 volc 路由共用一组 AK/SK（settings.volc）：个人版各自固定一个 Action，
  // 企业版/团队版走 ListSeatInfos → GetSeatAFPUsage / GetSeatInfoUsage 两步。
  // ── arkcli（官方 CLI）安装的路由 ──────────────────────────────────────────
  // 官方 CLI 的 `arkcli helper configure deepseek-harness` 把 provider 写成
@@ -87,7 +88,7 @@ const IDS = Object.keys(PROVIDERS);
 const ARK_IDS = IDS.filter(id => PROVIDERS[id].credentialKind === "volc");
 const ARK_DEFAULT_ON = ARK_IDS.some(id => PROVIDERS[id].defaultEnabled !== false);
 /**
- * 某条路由当前是否启用。Ark 以**组开关为唯一真源**——7 条路由共用一组 IAM AK/SK、一般用户只
+ * 某条路由当前是否启用。Ark 以**组开关为唯一真源**——4 条路由共用一组 IAM AK/SK、一般用户只
  * 持有一个套餐，所以设置页只给一个开关。这里必须与 Client 的 `providerEnabled` 同语义：
  * 两端口径一旦分叉，界面按组开关显示这条路由，Host 却按逐条值回 `disabled`，
  * 用户拿到的就是一张写着「检测已关闭」的空卡片（这正是 Coding Plan 查不到用量的原因）。
@@ -118,7 +119,7 @@ const PROVIDER_ALIASES = {
 function normalizeProviderKey(value) { return String(value ?? "").trim().toLowerCase().replace(/[\s._-]+/g, ""); }
 /**
  * 归一化索引：id 与别名都进同一张表，因此「精确 id」只是这张表的一个特例。
- * 一个键可以指向多条路由（`zai` → 中国版 + 国际版，`ark` → 7 条）。
+ * 一个键可以指向多条路由（`zai` → 中国版 + 国际版，`ark` → 4 条）。
  */
 const PROVIDER_LOOKUP = (() => {
 	const map = new Map();
@@ -139,7 +140,7 @@ const PROVIDER_LOOKUP = (() => {
  * 1. 认不出的原串**原样返回**而不是丢掉——调用方要能拿到「这个名字不认识，可用的是……」才能
  *    自我纠正；静默过滤只会让它以为本机没有额度。
  * 2. 一个名字命中多条路由时**全部返回**，各自带着真实状态（没启用的会如实标 disabled）。
- *    例如 `zai` 同时是中国版与国际版、`ark` 是 7 条路由：宁可多给几条数据让调用方自己判断，
+ *    例如 `zai` 同时是中国版与国际版、`ark` 是 4 条路由：宁可多给几条数据让调用方自己判断，
  *    也不替它猜一条，更不能返回空。
  * @param requested 调用方给的原始名字列表。
  */
@@ -192,7 +193,8 @@ function commandCodeAuthFileKey(io) {
 }
 // SuperGrok / X Premium 订阅（dsh-grok-kit 的 xai-oauth 路由）：用量走官方 Grok CLI 的计费
 // 代理（转发后端 GetGrokCreditsConfig）。凭据是 dsh-grok-kit / Grok CLI 共享登录文件里的
-// OAuth Bearer（短命轮换），只读不写、不自行刷新，避免与两端的 refresh-token 轮换互相顶掉。
+// OAuth Bearer（短命轮换）：平时只读；token 过期时借 dsh-grok-kit 的官方会话链（getAuth）经同一
+// 把写锁续约并写回同一文件，绝不自行裸 POST 刷新——后者才会顶掉两端的 refresh-token 轮换。
 const GROK_API_BASE = "https://cli-chat-proxy.grok.com/v1";
 // 官方 GrokComConfig.token_header 默认值：必须是该字符串，nginx 鉴权子请求才路由到 OAuth。
 const GROK_TOKEN_AUTH = "xai-grok-cli";
@@ -200,6 +202,21 @@ const GROK_CLIENT_VERSION = "1.0.13";
 const GROK_AUTH_FILE = join(homedir(), ".grok", "auth.json");
 // dsh-grok-kit 旧版私存路径（其 resolveXaiOAuthStorePath 的回退分支）。
 const XAI_OAUTH_AUTH_FILE = join(homedir(), ".dsh", ".xai-oauth-auth.json");
+// dsh-grok-kit 是兄弟插件而非本插件依赖：动态加载，解析不到（未安装 / 开发期 link 布局）即降级。
+// 0.2.0 起导出 XaiOAuthSession；其 models.getAuth("xai") 与 grok-kit 聊天/搜索走同一条官方 OAuth
+// 刷新链——共享文件 store、写锁内二次检查与 compare-and-write，多个消费者并发也只刷新一次，
+// 借它刷新不会顶掉 refresh-token 轮换（自己裸 POST 才会）。只缓存成功解析：失败（未安装、
+// 旧版本）下次过期时重试，用户中途安装/升级 grok-kit 后无需重启 DSH。
+let grokKitModule;
+function loadGrokKit() {
+ if (grokKitModule) return Promise.resolve(grokKitModule);
+ return import("dsh-grok-kit")
+  .then(mod => {
+   if (mod && typeof mod.XaiOAuthSession === "function") grokKitModule = mod;
+   return grokKitModule;
+  })
+  .catch(() => undefined);
+}
 // Bearer 的 JWT payload 里有 sub（= user_id）；登录文件缺 user_id 时兜底取它。
 function bearerSubject(key) {
  try {
@@ -414,10 +431,13 @@ function volcFailure(action, error) {
 }
 async function fetchJson(fetcher, url, headers, lifetimeSignal, init = {}) {
  let response;
- try { response = await fetcher(url, { method: init.method ?? "GET", ...(init.body !== undefined ? { body: init.body } : {}), headers: { accept: "application/json", "user-agent": "dsh-subusage/0.10.10", ...headers }, signal: lifetimeSignal ? AbortSignal.any([AbortSignal.timeout(10000), lifetimeSignal]) : AbortSignal.timeout(10000), redirect: "manual" }); }
+ try { response = await fetcher(url, { method: init.method ?? "GET", ...(init.body !== undefined ? { body: init.body } : {}), headers: { accept: "application/json", "user-agent": `dsh-subusage/${VERSION}`, ...headers }, signal: lifetimeSignal ? AbortSignal.any([AbortSignal.timeout(10000), lifetimeSignal]) : AbortSignal.timeout(10000), redirect: "manual" }); }
  catch { throw failure("subusage/network", "网络请求失败或超时", true); }
- if (response.status >= 300 && response.status < 400 || response.status === 401 || response.status === 403) throw failure("subusage/auth", "登录或凭据已失效");
- if (!response.ok) {
+ // 3xx（redirect: "manual" 下的域名迁移/跳转）不是鉴权失败，与 401/403 分开映射，
+ // 避免用户被误导去重登录；两个条件都加显式括号，不依赖 &&/|| 优先级。
+ if ((response.status >= 300 && response.status < 400)) throw failure("subusage/response", "服务端返回了意外的重定向响应（HTTP 3xx）");
+ if ((response.status === 401 || response.status === 403)) throw failure("subusage/auth", "登录或凭据已失效");
+ if (!response.ok && !(init.notSubscribed404 === true && response.status === 404)) {
   const retry = response.status === 408 || response.status === 429 || response.status >= 500;
   const raw = response.headers?.get?.("retry-after");
   const retryAfterMs = raw ? (/^\d+(\.\d+)?$/.test(raw) ? Number(raw) * 1000 : Math.max(0, Date.parse(raw) - Date.now())) : undefined;
@@ -433,7 +453,8 @@ async function fetchJson(fetcher, url, headers, lifetimeSignal, init = {}) {
  } catch (e) { if (e instanceof RemoteError) throw e; throw failure("subusage/network", "读取响应失败", true); }
  let body;
  try { body = JSON.parse(text); } catch { throw failure("subusage/response", "响应不是合法 JSON"); }
- if ([401, 403, "401", "403"].includes(body?.code)) throw failure("subusage/auth", "登录或凭据已失效");
+ if (response.status === 404 && init.notSubscribed404 === true && !/^(NotFound\.BillingType|OperationDenied\.NotSubscribed)$/.test(body?.ResponseMetadata?.Error?.Code ?? "")) throw failure("subusage/http", "HTTP 404");
+  if ([401, 403, "401", "403"].includes(body?.code)) throw failure("subusage/auth", "登录或凭据已失效");
  return body;
 }
 function numeric(v) { return typeof v === "number" && Number.isFinite(v) && v >= 0; }
@@ -446,7 +467,10 @@ const RANK = { month: 0, sub: 0, period: 0, week: 1, "7d": 1, day: 2, "5h": 2, r
 function cascadeRateLimited(windows) {
  const roots = windows.filter(w => w.status === "rate-limited");
  for (const w of windows) {
-  const blockers = roots.filter(root => (RANK[root.kind] ?? 3) < (RANK[w.kind] ?? 3));
+  const blockers = roots.filter(root => {
+    const sourceScope = root.detail?.scope ?? "all", targetScope = w.detail?.scope ?? "all";
+    return (sourceScope === "all" || sourceScope === targetScope) && (RANK[root.kind] ?? 3) < (RANK[w.kind] ?? 3);
+   });
   if (blockers.length) { if (w.status !== "rate-limited") w.cascade = true; w.status = "rate-limited"; w.detail = { ...w.detail, blockedBy: [...new Set(blockers.map(root => root.kind))] }; }
  }
  return windows;
@@ -538,7 +562,12 @@ export function normalizeNanoGpt(body, balanceBody) {
  const extras = [{ kind: "plan", value: body.state }];
  const usd = typeof balanceBody?.usd_balance === "string" && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(balanceBody.usd_balance.trim()) ? balanceBody.usd_balance.trim() : undefined;
  if (usd) extras.push({ kind: "balance", value: `${usd} USD` });
- return { windows: cascadeRateLimited(windows), extras, coverage: windows.length && !partial ? "complete" : "partial" };
+ const routing = body?.routing;
+  const mode = routing?.recommendedMode;
+  const availability = mode === "unavailable" ? { availability: "blocked", availabilityReason: "routing-policy" }
+   : mode === "subscription" ? { availability: routing.subscriptionQuotaAvailable === true ? "included" : "unknown", availabilityReason: "routing-advice" }
+   : mode === "paygo" ? { availability: usd !== undefined && Number.isFinite(Number(usd)) && Number(usd) > 0 && routing.paidSpendPolicyAllowsBalance !== false ? "paygo" : "unknown", availabilityReason: "routing-advice" } : {};
+  return { windows: cascadeRateLimited(windows), extras, coverage: (windows.length || usd !== undefined || mode === "unavailable") && !partial ? "complete" : "partial", ...availability };
 }
 // 官方 CLI 的计数消歧规则：有 remaining_percent 时按它校准；旧响应 usage_count 是剩余。
 // https://github.com/MiniMax-AI/cli/blob/main/src/utils/quota.ts
@@ -582,7 +611,8 @@ export function normalizeMinimax(body) {
   const reset = numeric(endTime) && endTime > 0 && Number.isFinite(new Date(endTime).getTime()) ? new Date(endTime).toISOString() : undefined;
   windows.push(windowRow(kind, usedPercent, reset, undefined, detail));
  }
- return { windows: cascadeRateLimited(windows), extras: [], coverage: windows.length === 2 ? "complete" : "partial" };
+ const unlimited = !windows.length && row.current_interval_status === 3 && row.current_weekly_status === 3;
+  return { windows: cascadeRateLimited(windows), extras: unlimited ? [{ kind: "quota-status", value: "unlimited" }] : [], coverage: windows.length || [row.current_interval_status, row.current_weekly_status].includes(3) ? "complete" : "partial" };
 }
 export function normalizeCommandCode(body, subscriptionBody) {
  // 输入是 Command Code 计费接口（/alpha/billing/credits）的原始响应体。
@@ -622,7 +652,11 @@ export function normalizeCommandCode(body, subscriptionBody) {
  if (reported.length) extras.push({ kind: "balance", value: `${Math.round(reported.reduce((sum, v) => sum + Math.max(0, v), 0) * 100) / 100} credits` });
  // 月池耗尽并不证明已购/赠送池或短窗口也不可用；只级联接口的周/5小时限制。
   cascadeRateLimited(windows.filter(w => w.kind !== "month"));
-  return { windows, extras, coverage: hasMonthlyBalance && monthlyCap !== undefined ? "complete" : "partial" };
+  const exhausted = windows.some(w => w.status === "rate-limited");
+   const purchased = credits.purchasedCredits;
+   const availability = exhausted && numeric(purchased) && purchased > 0 ? { availability: "paygo", availabilityReason: "paid-credits" }
+    : exhausted ? { availability: "blocked", availabilityReason: "quota-exhausted" } : {};
+   return { windows, extras, coverage: hasMonthlyBalance || windows.length || reported.length ? "complete" : "partial", ...availability };
 }
 // SuperGrok / X Premium 统一用量池：GetGrokCreditsConfig 响应（官方 grok CLI 的
 // /v1/billing?format=credits）。creditUsagePercent 是“已用”百分比（0-100），剩余由
@@ -668,11 +702,14 @@ export function normalizeSiliconFlow(body) {
 }
 // Codex / ChatGPT 订阅用量：rate_limit.primary_window 与 secondary_window 各含 used_percent 与
 // resets_at。免费档的次窗口是 30 天，所以有 window_seconds 时按它判窗口名，缺失时按位置回退 5h / 7d。
-// credits 只在真正报告了可用余额时显示：has_credits=false、unlimited=true、balance="0" 都不显示，
+// credits 只在真正报告了可用余额时显示：has_credits=false、balance="0" 不画余额；unlimited 单独保留状态，
 // 不把「无额度」画成 0。
 // https://raw.githubusercontent.com/steipete/CodexBar/main/docs/codex.md
 export function normalizeCodexUsage(body) {
 	const windows = [];
+	const plan = typeof body?.plan_type === "string" ? body.plan_type.trim() : "";
+	// 当前 Pro 三档无短窗；未知档位的缺失时长不按主窗口位置猜成 5h。
+	const weeklyOnly = ["pro", "prolite", "promax"].includes(plan.toLowerCase());
 	const windowKind = (row, fallback) => {
 		const seconds = row?.window_seconds ?? row?.limit_window_seconds;
 		if (!Number.isFinite(seconds) || seconds <= 0) return fallback;
@@ -689,18 +726,35 @@ export function normalizeCodexUsage(body) {
 		windows.push(windowRow(windowKind(row, fallback), row.used_percent, reset));
 	};
 	const limits = body?.rate_limit && typeof body.rate_limit === "object" && !Array.isArray(body.rate_limit) ? body.rate_limit : {};
-	push(limits.primary_window, "5h");
-	push(limits.secondary_window, "7d");
-	// HTTP 200 但没有任何窗口 = 该账号没有可读的订阅额度，不是 0% 用量。
-	if (!windows.length) return { windows: [], extras: [{ kind: "plan", value: "未检测到订阅额度窗口" }], coverage: "partial" };
+	const positional = !plan || ["plus", "team", "business"].includes(plan.toLowerCase());
+	push(limits.primary_window, weeklyOnly ? "week" : positional ? "5h" : "rolling");
+	push(limits.secondary_window, weeklyOnly ? "week" : positional ? "7d" : "rolling");
 	const extras = [];
-	// 实测：plan_type 给套餐档位（如 "plus"），值得显示。
-	const plan = typeof body?.plan_type === "string" && body.plan_type.trim() ? body.plan_type.trim() : "";
 	if (plan) extras.push({ kind: "plan", value: plan });
 	const credits = body?.credits && typeof body.credits === "object" && !Array.isArray(body.credits) ? body.credits : {};
 	const balance = typeof credits.balance === "string" && credits.balance.trim() ? credits.balance.trim() : typeof credits.balance === "number" ? String(credits.balance) : "";
-	if (credits.has_credits === true && credits.unlimited !== true && balance && balance !== "0") extras.push({ kind: "balance", value: balance });
-	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length >= 2 ? "complete" : "partial" };
+	const creditBalance = balance && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(balance) && Number.isFinite(Number(balance)) ? Number(balance) : undefined;
+	if (credits.has_credits === true && credits.unlimited !== true && creditBalance !== undefined && creditBalance > 0) extras.push({ kind: "balance", value: balance });
+	if (credits.has_credits === true && credits.unlimited === true) extras.push({ kind: "credit-status", value: "unlimited" });
+	const control = body?.spend_control;
+	const member = control?.individual_limit;
+	const memberLimit = Number(member?.limit), memberUsed = member?.used == null ? NaN : Number(member.used);
+	if (member && Number.isFinite(memberLimit) && memberLimit > 0 && Number.isFinite(memberUsed) && memberUsed >= 0) {
+		const reset = numeric(member.reset_at) && member.reset_at > 0 ? new Date(member.reset_at * 1000).toISOString() : undefined;
+		windows.push({ ...windowRow("period", memberUsed / memberLimit * 100, reset, undefined, { used: memberUsed, limit: memberLimit, unit: "credits", scope: "member-budget" }), groupLabel: "Member budget" });
+	}
+	const reached = body?.rate_limit_reached_type?.kind;
+	const restricted = control?.reached === true || ["workspace_owner_credits_depleted", "workspace_member_credits_depleted", "workspace_owner_usage_limit_reached", "workspace_member_usage_limit_reached"].includes(reached);
+	const exhausted = windows.some(w => w.status === "rate-limited") || limits.limit_reached === true || limits.allowed === false;
+	const creditFallback = credits.has_credits === true && (credits.unlimited === true || creditBalance > 0);
+	const availability = restricted ? { availability: "blocked", availabilityReason: "spend-control" }
+		: exhausted && creditFallback ? { availability: "unknown", availabilityReason: "credit-eligibility" }
+		: exhausted ? { availability: "blocked", availabilityReason: "quota-exhausted" } : {};
+	if (!windows.length && !extras.some(e => e.kind !== "plan") && !restricted) extras.push({ kind: "note", value: "未检测到订阅额度窗口" });
+	const reported = windows.length || extras.some(e => e.kind !== "plan" && e.kind !== "note") || restricted;
+	// 额外特性池未按所选模型映射前，不声称已完整覆盖它们。
+	const partial = Array.isArray(body?.additional_rate_limits) && body.additional_rate_limits.length > 0;
+	return { windows: cascadeRateLimited(windows), extras, coverage: reported && !partial ? "complete" : "partial", ...availability };
 }
 // DeepSeek 官方余额（余额型）：GET https://api.deepseek.com/user/balance，Bearer 与推理同一把 Key。
 // 响应 { is_available, balance_infos: [{ currency, total_balance, granted_balance, topped_up_balance }] }，
@@ -741,14 +795,17 @@ export function normalizeOpenRouter(keyBody, creditBody) {
 	const total = num(credits?.total_credits), spent = num(credits?.total_usage);
 	if (total !== undefined && spent !== undefined) extras.push({ kind: "balance", value: `${Math.round(Math.max(0, total - spent) * 100) / 100} USD` });
 	if (data.is_free_tier === true) extras.push({ kind: "plan", value: "Free tier" });
-	if (!windows.length && !extras.length) throw failure("subusage/response", "OpenRouter 响应没有可用的限额或余额");
-	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length ? "complete" : "partial" };
+	if (!windows.length && num(data.usage) !== undefined) extras.push({ kind: "spend", value: `${Math.round(data.usage * 100) / 100} USD` });
+	if (!windows.length && !extras.length) throw failure("subusage/response", "OpenRouter 响应没有可用的限额、余额或用量");
+	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length || extras.some(e => e.kind !== "plan") ? "complete" : "partial" };
 }
 // ── 余额型聚合商（各家单位与形状都不同，逐个显式换算，不做通用折算）────────────────
 /** Novita：金额单位是 1/10000 USD（10000 = $1.00）。 */
 export function normalizeNovitaBalance(body) {
-	const num = value => typeof value === "number" && Number.isFinite(value) ? value : undefined;
-	const available = num(body?.availableBalance);
+	// 官方金额为十进制字符串；不接受空串、指数或十六进制等非金额写法。
+	const raw = body?.availableBalance;
+	const available = typeof raw === "number" && Number.isFinite(raw) ? raw
+		: typeof raw === "string" && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(raw.trim()) && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
 	if (available === undefined) throw failure("subusage/response", "Invalid Novita balance response");
 	return { windows: [], extras: [{ kind: "balance", value: `${Math.round(available / 100) / 100} USD` }], coverage: "complete" };
 }
@@ -789,7 +846,7 @@ export function normalizeOllamaCloudUsage(body) {
 		windows.push(windowRow(kind, Math.min(100, usage * 100)));
 	}
 	if (!windows.length) throw failure("subusage/response", "Ollama Cloud 响应没有可用的额度窗口");
-	return { windows: cascadeRateLimited(windows), extras: [], coverage: windows.length >= 3 ? "complete" : "partial" };
+	return { windows: cascadeRateLimited(windows), extras: [], coverage: "complete" };
 }
 /** Vercel AI Gateway：balance / total_used 是十进制字符串；没有限额也没有重置，只显示金额。 */
 export function normalizeVercelCredits(body) {
@@ -806,12 +863,14 @@ export function normalizeZenmux(subscriptionBody, balanceBody) {
 	const num = value => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 	const windows = [], extras = [];
 	const data = subscriptionBody?.data && typeof subscriptionBody.data === "object" && !Array.isArray(subscriptionBody.data) ? subscriptionBody.data : {};
-	const quota = data.quota_5_hour && typeof data.quota_5_hour === "object" ? data.quota_5_hour : {};
-	const usage = num(quota.usage_percentage);
-	if (usage !== undefined) {
+	for (const [field, kind] of [["quota_5_hour", "5h"], ["quota_7_day", "week"]]) {
+		const quota = data[field];
+		if (quota === undefined || quota === null) continue;
+		if (typeof quota !== "object" || Array.isArray(quota) || num(quota.usage_percentage) === undefined) throw failure("subusage/response", "Invalid ZenMux quota window");
 		const detail = num(quota.used_flows) !== undefined && num(quota.max_flows) !== undefined ? { used: quota.used_flows, limit: quota.max_flows, unit: "flows" } : undefined;
-		windows.push(windowRow("5h", Math.min(100, usage * 100), typeof quota.resets_at === "string" ? quota.resets_at : undefined, undefined, detail));
+		windows.push(windowRow(kind, quota.usage_percentage * 100, typeof quota.resets_at === "string" ? quota.resets_at : undefined, undefined, detail));
 	}
+	// quota_monthly 只有上限，未报告实时用量；不从短窗拼造月百分比。
 	const tier = data.plan && typeof data.plan.tier === "string" ? data.plan.tier.trim() : "";
 	if (tier) extras.push({ kind: "plan", value: tier });
 	const balance = balanceBody?.data && typeof balanceBody.data === "object" && !Array.isArray(balanceBody.data) ? balanceBody.data : {};
@@ -821,7 +880,7 @@ export function normalizeZenmux(subscriptionBody, balanceBody) {
 		extras.push({ kind: "balance", value: `${Math.round(total * 100) / 100} ${currency}`.trim() });
 	}
 	if (!windows.length && !extras.length) throw failure("subusage/response", "ZenMux 响应没有可用的配额或余额");
-	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length ? "complete" : "partial" };
+	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length || total !== undefined ? "complete" : "partial", ...(["suspended", "banned"].includes(data.account_status) ? { availability: "blocked", availabilityReason: "account-restricted" } : {}) };
 }
 /**
  * LiteLLM 的管理端点在 **proxy 根**（不是 /v1）：去掉尾部斜杠与常见的 /v1 后缀，
@@ -838,7 +897,7 @@ export function litellmRoot(baseUrl) {
 }
 /**
  * LiteLLM：`/key/info` 给 key 自身的预算与花费，`/user/info`｜`/team/info` 给更完整的视图。
- * 有预算上限才画进度；**没有上限时不编造百分比**，只如实显示已用金额。
+ * 各预算同时生效，分别保留；**没有上限时不编造百分比**，只如实显示已用金额。
  * 接口不给重置时刻时不显示重置（别把金额渲染成倒计时）。
  * https://docs.litellm.ai/docs/proxy/virtual_keys
  */
@@ -848,17 +907,25 @@ export function normalizeLitellm(keyBody, budgetBody) {
 	// 真实响应是 `{ key, info: {...} }`；也接受直接把字段放在顶层。
 	const keyInfo = pick(keyBody?.info) ?? pick(keyBody);
 	if (!keyInfo) throw failure("subusage/response", "Invalid LiteLLM key info response");
-	const scope = pick(budgetBody) ?? {};
-	const spend = num(scope.spend) ?? num(keyInfo.spend);
-	const maxBudget = num(scope.max_budget) ?? num(keyInfo.max_budget);
-	const resetAt = typeof scope.budget_reset_at === "string" ? scope.budget_reset_at : typeof keyInfo.budget_reset_at === "string" ? keyInfo.budget_reset_at : undefined;
+	const scopes = [["key", keyInfo]];
+	for (const body of Array.isArray(budgetBody) ? budgetBody : [budgetBody]) {
+		if (pick(body?.team_info)) scopes.push(["team", body.team_info]);
+		else if (pick(body?.user_info)) scopes.push(["user", body.user_info]);
+		else if (pick(body)) scopes.push(["scope", body]);
+	}
+	const windows = [], extras = [];
 	const round = value => Math.round(value * 100) / 100;
-	if (spend !== undefined && maxBudget !== undefined && maxBudget > 0) {
-		return { windows: [windowRow("period", Math.min(100, spend / maxBudget * 100), resetAt, undefined, { used: round(spend), limit: round(maxBudget), unit: "USD" })], extras: [], coverage: "complete" };
+	for (const [scope, row] of scopes) {
+		const spend = num(row.spend), maxBudget = num(row.max_budget);
+		if (spend === undefined || spend < 0) continue;
+		if (maxBudget !== undefined && maxBudget > 0) {
+			const resetAt = typeof row.budget_reset_at === "string" ? row.budget_reset_at : undefined;
+			windows.push({ ...windowRow("period", spend / maxBudget * 100, resetAt, undefined, { used: round(spend), limit: round(maxBudget), unit: "USD" }), ...(scopes.length > 1 ? { budgetScope: scope } : {}) });
+		} else extras.push({ kind: scope === "key" ? "spend" : `${scope}-spend`, value: `${round(spend)} USD` });
 	}
-	// 没有预算上限：没有百分比可算，如实给金额。
-	if (spend !== undefined) return { windows: [], extras: [{ kind: "spend", value: `${round(spend)} USD` }], coverage: "complete" };
-	throw failure("subusage/response", "LiteLLM 响应没有可用的预算或花费");
+	if (!windows.length && !extras.length) throw failure("subusage/response", "LiteLLM 响应没有可用的预算或花费");
+	// 各预算同时约束，不用更宽松的上级覆盖 Key。
+	return { windows, extras, coverage: "complete" };
 }
 function detectConfigured(ctx) {
  try { const ids = new Set(ctx.llm.listProviders().map(p => p.id)); return Object.fromEntries(IDS.map(id => [id, ids.has(id)])); }
@@ -927,6 +994,8 @@ export class SubUsageService extends TypertRemoteService {
  this.authFile = options.resolveAuthFile ?? (async () => commandCodeAuthFileKey(this.io));
   // SuperGrok 只读共享登录文件（~/.grok/auth.json 等）取 OAuth Bearer；可注入仅供隔离测试。
   this.grokAuth = options.resolveGrokAuth ?? (async () => grokAuthFileCredentials(this.io));
+  // 过期时借 dsh-grok-kit 的官方会话链刷新同一登录文件；解析不到兄弟插件时返回 undefined 并降级。
+  this.resolveGrokKit = options.resolveGrokKit ?? loadGrokKit;
   // Codex 只读共享登录文件（$CODEX_HOME/auth.json 或 ~/.codex/auth.json）取 OAuth access token。
   this.codexAuth = options.resolveCodexAuth ?? (async () => codexAuthFileCredentials(this.io, { CODEX_HOME: (await this.environmentByName("CODEX_HOME"))?.value }));
   this.cache = new Map(); this.inflight = new Map(); this.generations = new Map(); this.fingerprints = new Map(); this.disposed = false; this.controller = new AbortController();
@@ -998,6 +1067,33 @@ export class SubUsageService extends TypertRemoteService {
   if (typeof envAk?.value === "string" && envAk.value.trim() && typeof envSk?.value === "string" && envSk.value.trim()) return { key: envAk.value.trim(), secret: envSk.value.trim(), source: "env" };
   return ak && sk ? { key: ak, secret: sk, source: "manual" } : { key: undefined, secret: undefined, source: "none" };
  }
+ /**
+  * Grok 登录文件的 access token 过期时，借 dsh-grok-kit 的官方会话链续约：getAuth("xai")
+  * 在共享凭据 store 的写锁内二次检查并刷新，新 token 由官方链写回同一个 ~/.grok/auth.json，
+  * 与 grok-kit 聊天/搜索/Grok CLI 是同一套锁协议，不会顶掉 refresh-token 轮换。
+  * 不直接信任 getAuth 返回值：无论刷新由本进程还是并发的另一进程完成，一律重读登录文件拿新 token 与新过期时间。
+  * 回到 { renewed:true, identity }；兄弟插件不可用时 unavailable:true；刷新尝试失败时带 refreshError。
+  */
+ async renewGrokIdentity(identity, signal) {
+  if (!identity.expiresAt || Date.parse(identity.expiresAt) > this.now()) return { renewed: false, unavailable: true, identity };
+  let kit;
+  try { kit = await this.resolveGrokKit(); } catch { kit = undefined; }
+  if (!kit?.XaiOAuthSession) return { renewed: false, unavailable: true, identity };
+  let session;
+  let refreshError;
+  try {
+   session = new kit.XaiOAuthSession();
+   // pi-ai 内部有 15s 刷新超时与 2s 文件锁预算；外层再兜 20s 总预算，避免挂死药丸/工具刷新。
+   const deadline = AbortSignal.timeout(20000);
+   await session.models.getAuth("xai", { signal: signal ? AbortSignal.any([signal, deadline]) : deadline });
+  } catch (error) { refreshError = error; }
+  finally { try { session?.dispose?.(); } catch { /* 会话只持有进程内模型缓存，dispose 失败无后果 */ } }
+  const cred = await this.grokAuth();
+  if (cred?.key && cred.key !== identity.key && (!cred.expiresAt || Date.parse(cred.expiresAt) > this.now())) {
+   return { renewed: true, identity: { key: cred.key, source: "auth-file", ...(cred.userId ? { userId: cred.userId } : {}), ...(cred.expiresAt ? { expiresAt: cred.expiresAt } : {}) } };
+  }
+  return { renewed: false, unavailable: false, refreshError, identity };
+ }
  async fetchProvider(id, identity, settings, signal = this.controller.signal) {
   const get = (url, headers, init) => fetchJson(this.fetcher, url, headers, signal, init);
   // 火山方舟额度走管控面 OpenAPI：POST 根路径 + Action/Version 在 query，鉴权是 AK/SK 签名。
@@ -1006,7 +1102,7 @@ export class SubUsageService extends TypertRemoteService {
    const call = async (action, payload) => {
     const body = payload === undefined ? "{}" : JSON.stringify(payload);
     const signed = volcSignature({ accessKeyId: identity.key, secretAccessKey: identity.secret, action, host: spec.volcHost, region: spec.volcRegion, body });
-    const response = await get(signed.url, signed.headers, { method: "POST", body });
+    const response = await get(signed.url, signed.headers, { method: "POST", body, notSubscribed404: true });
     const apiError = volcError(response);
     // 「这个账号没有这份套餐」不是故障，是答案：实测没有 BytePlus Coding Plan 的账号会返回
     // HTTP 404 `NotFound.BillingType`（coding plan config is not exist），`OperationDenied.NotSubscribed`
@@ -1051,7 +1147,7 @@ export class SubUsageService extends TypertRemoteService {
    // HTTP 200 但窗口为空是「未订阅」，不是 0% 用量：显式说明，不画零额度的假象。
    else if (!windows.length) extras.push({ kind: "plan", value: parsed.subscribed ? "本周期暂无窗口数据" : "未检测到该套餐订阅" });
    // 订阅状态要**结构化**带出去，不能只写进 extras 文案：同一组 AK/SK 能查到名下所有套餐，
-   // 界面上若把 7 条路由一律列出来，用户根本分不清哪个是哪个。前端据此收起没订阅的那些。
+   // 界面上若把 4 条路由一律列出来，用户根本分不清哪个是哪个。前端据此收起没订阅的那些。
    return { windows, extras, coverage: windows.length ? "complete" : "partial", subscribed: parsed.subscribed === true };
   }
   const headers = { authorization: `Bearer ${identity.key}` };
@@ -1108,10 +1204,14 @@ export class SubUsageService extends TypertRemoteService {
    const keyInfo = await get(`${root}/key/info`, headers);
    const own = keyInfo?.info && typeof keyInfo.info === "object" && !Array.isArray(keyInfo.info) ? keyInfo.info : {};
    // 更完整的预算视图在 user/team info；拿不到就退回 key 自身的 info。
-   const scoped = typeof own.team_id === "string" && own.team_id.trim() ? `/team/info?team_id=${encodeURIComponent(own.team_id.trim())}`
-    : typeof own.user_id === "string" && own.user_id.trim() ? `/user/info?user_id=${encodeURIComponent(own.user_id.trim())}` : "";
-   const budget = scoped ? await get(`${root}${scoped}`, headers).catch(() => undefined) : undefined;
-   return normalizeLitellm(keyInfo, budget);
+   const scopes = [["team", own.team_id], ["user", own.user_id]].filter(([, value]) => typeof value === "string" && value.trim());
+   const budgets = await Promise.all(scopes.map(async ([scope, value]) => {
+     const body = await get(`${root}/${scope}/info?${scope}_id=${encodeURIComponent(value.trim())}`, headers).catch(() => undefined);
+     return body ? body[`${scope}_info`] ? body : { [`${scope}_info`]: body } : undefined;
+    }));
+   const data = normalizeLitellm(keyInfo, budgets);
+    if (budgets.some(body => body === undefined)) data.coverage = "partial";
+    return data;
   }
   if (id === "commandcode") {
    // 与提供方插件同一凭据来源，但直连计费接口并行拉取：其 report() 会对每个账户
@@ -1121,20 +1221,30 @@ export class SubUsageService extends TypertRemoteService {
     get(`${COMMAND_CODE_API_BASE}/alpha/billing/credits`, billingHeaders),
     get(`${COMMAND_CODE_API_BASE}/alpha/billing/subscriptions`, billingHeaders).catch(() => undefined)
    ]);
-   return normalizeCommandCode(credits, subscription);
+   const data = normalizeCommandCode(credits, subscription);
+    if (subscription === undefined) data.coverage = "partial";
+    return data;
   }
   if (id === "xai-oauth") {
-   // 登录文件里的 access token 短命（实测 ~24 小时）。本插件**刻意不代刷**——refresh-token 轮换由
-   // Grok CLI / dsh-grok-kit 各自的锁协议管理，第三端刷新会把它们的轮换顶掉。但「过期」这件事必须
-   // 说清楚：不发这一枪的话，用户看到的是上游 401 转成的「登录或凭据已失效」，而他那边的 Grok Kit
-   // 明明写着「已登录」——两边对不上，只会让人以为插件坏了。
-   if (identity.expiresAt && Date.parse(identity.expiresAt) <= this.now()) {
-    throw failure("subusage/auth", `Grok 登录文件的 access token 已于 ${new Date(identity.expiresAt).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })} 过期。用一次 Grok CLI，或在 设置 → xAI Grok 里重新登录，都会刷新同一个文件（${GROK_AUTH_FILE}）；本插件不代刷，以免与它们的 refresh-token 轮换互相顶掉。`);
+   // 登录文件里的 access token 短命（实测 6 小时量级），而 grok-kit 的自动刷新是懒触发：
+   // 只有它自己聊天/搜索遇到过期才刷，没有后台定时器。本插件每分钟读一次用量，是最常发现
+   // 过期的一方——若只读不刷，就会出现「Grok Kit 显示已登录、用量卡片显示已过期」的割裂。
+   // 过期时借 grok-kit 的官方会话链续约（同一文件、同一把写锁、compare-and-write，不顶轮换）；
+   // 兄弟插件不可用或刷新失败时，才退回可行动的手动提示。
+   let grok = identity;
+   if (grok.expiresAt && Date.parse(grok.expiresAt) <= this.now()) {
+    const outcome = await this.renewGrokIdentity(grok, signal);
+    if (outcome.renewed) grok = outcome.identity;
+    else if (outcome.unavailable) throw failure("subusage/auth", `Grok 登录文件的 access token 已于 ${new Date(identity.expiresAt).toLocaleString("zh-CN")} 过期，但本机未能加载 dsh-grok-kit（≥0.2.0）的自动刷新链。用一次 Grok CLI（登录后发一条消息），或在 设置 → xAI Grok 里重新登录，都会刷新同一个文件（${GROK_AUTH_FILE}）。`);
+    else {
+     const reason = outcome.refreshError?.message ? String(outcome.refreshError.message).slice(0, 200) : "登录刷新链未返回新凭据";
+     throw failure("subusage/auth", `Grok 登录已于 ${new Date(identity.expiresAt).toLocaleString("zh-CN")} 过期，尝试经 dsh-grok-kit 自动刷新失败：${reason}。通常需要重新登录：在 设置 → xAI Grok 重新登录，或运行 grok login（同一登录文件 ${GROK_AUTH_FILE}）。`);
+    }
    }
    // 直连官方 Grok CLI 计费代理；X-XAI-Token-Auth 的取值是 token_header 字符串（xai-grok-cli）
    // 而非布尔，x-userid 取登录文件。套餐名走 /v1/settings（subscription_tier_display），
    // 失败不阻塞用量（回退 billing 响应里的 subscription_tier）。
-   const grokHeaders = { ...headers, "x-xai-token-auth": GROK_TOKEN_AUTH, "x-grok-client-version": GROK_CLIENT_VERSION, ...(identity.userId ? { "x-userid": identity.userId } : {}) };
+   const grokHeaders = { authorization: `Bearer ${grok.key}`, "x-xai-token-auth": GROK_TOKEN_AUTH, "x-grok-client-version": GROK_CLIENT_VERSION, ...(grok.userId ? { "x-userid": grok.userId } : {}) };
    const [billing, settings] = await Promise.all([
     get(`${GROK_API_BASE}/billing?format=credits`, grokHeaders),
     get(`${GROK_API_BASE}/settings`, grokHeaders).catch(() => undefined)
@@ -1143,7 +1253,7 @@ export class SubUsageService extends TypertRemoteService {
   }
   if (id === "openai-codex") {
    // ChatGPT 后端私有接口：Bearer 是 Codex CLI 的 OAuth access token，不是 OPENAI_API_KEY。
-   return normalizeCodexUsage(await get(`${CODEX_API_BASE}/wham/usage`, headers));
+   return normalizeCodexUsage(await get(`${CODEX_API_BASE}/wham/usage`, { ...headers, ...(identity.accountId ? { "ChatGPT-Account-Id": identity.accountId } : {}) }));
   }
   const base = "https://platform.xiaomimimo.com/api/v1";
   const h = { cookie: identity.key, origin: "https://platform.xiaomimimo.com", referer: "https://platform.xiaomimimo.com/#/console/balance", "x-timezone": "UTC+08:00" };
@@ -1191,6 +1301,54 @@ export class SubUsageService extends TypertRemoteService {
    return { mode: activeId === "" ? "auto" : "fixed", activeId, accounts: accounts.map(account => ({ ...account, active: account.id === activeId })) };
   } catch { return null; }
  }
+ /**
+  * 自动轮换模式下的**轮换池健康摘要**：UI 通道（read/refresh）默认只回顶层 Key 单账户，
+  * 用户看到的是乐观数字，但实际请求会落到池中任意账户——默认账户健康不代表池健康
+  * （其余账户可能已全部 5h 限额）。这里复用各账户自己的缓存并行读一遍，把摘要挂到默认
+  * 账户 entry 上，Client 仅在 auto 模式渲染。固定模式（activeId 非空）返回 null。
+  *
+  * 业务口径（不能简单取「池中最紧张账户」）：各账户是**独立配额**，轮换器会避开已限额的
+  * 账户，所以单账户限额不是立即失败信号。只有「所有有凭据的账户都限额」才是池耗尽：
+  *   healthy  = ok 且没有 rate-limited 窗口
+  *   blocked  = ok 但至少一个窗口 rate-limited（容量降级，仍可能成功）
+  *   unusable = no-key/no-cookie/disabled/error（读不到或没凭据，不计入有效容量）
+  * 池里没有任何有凭据的账户时 exhausted=false（那是「未配置」，由默认 entry 的 no-key 表达）。
+  */
+ async commandCodePool(settings, force, defaultEntry) {
+  const plan = this.commandCodeAccountPlan();
+  if (!plan || plan.mode !== "auto") return null;
+  // 默认账户那条 entry 已由调用方读过（避免重复一发），其余账户各自命中 provider() 的 TTL/
+  // inflight 缓存，因此每分钟的自动刷新不会真的打 N 次计费接口。
+  const readOne = async (account) => {
+   if (account.id === "default") return defaultEntry;
+   try { return await this.provider("commandcode", settings, force, account.id); }
+   catch { return { ...this.base("commandcode", "none", settings, account.id), state: "error", errorCode: "subusage/internal", error: "读取用量失败", windows: [], extras: [] }; }
+  };
+  const entries = await Promise.all(plan.accounts.map(account => readOne(account)));
+  const accounts = plan.accounts.map((account, index) => {
+   const entry = entries[index];
+   const windows = Array.isArray(entry?.windows) ? entry.windows : [];
+   const ok = entry?.state === "ok";
+   const paid = entry?.availability === "paygo";
+   const limited = entry?.availability === "blocked" || windows.some(w => w.status === "rate-limited");
+   const known = paid || entry?.coverage !== "partial" && windows.length > 0;
+   return {
+    id: account.id, label: account.label, active: account.active === true,
+    state: entry?.state ?? "error", errorCode: entry?.errorCode, windows,
+    // usable：读到了且没有任何限额窗口；blocked：读到了但有窗口限额（容量降级，仍可能成功）。
+    usable: ok && (paid || known && !limited),
+     ...(ok && !known && !limited ? { availability: "unknown" } : entry?.availability ? { availability: entry.availability } : {}),
+    blocked: ok && !paid && limited
+   };
+  });
+  // 「有效容量」= usable + blocked（真的有凭据且读到了额度的账户）；no-key/error/disabled 不算。
+  const capable = accounts.filter(a => a.usable || a.blocked);
+  const available = accounts.filter(a => a.usable).length;
+  const blockedCount = accounts.filter(a => a.blocked).length;
+  const unusableCount = accounts.length - available - blockedCount;
+  const exhausted = capable.length > 0 && capable.every(a => a.blocked) && !accounts.some(a => a.state === "error" || a.availability === "unknown");
+  return { mode: "auto", total: accounts.length, available, blockedCount, unusableCount, exhausted, accounts };
+ }
  /** 按 id 失效一家 provider 的**全部账户**缓存：凭据/开关变化不能只影响默认账户那一条。 */
  invalidateProvider(id) {
   const keys = new Set([id]);
@@ -1229,7 +1387,7 @@ export class SubUsageService extends TypertRemoteService {
   }
   // fingerprint 计入账户选择：切换账户后同 id 缓存/inflight 不串账（不同账户 key 必不同）；
   // 空串与 "default" 同为默认账户，归一后共享缓存。
-  const fingerprint = hash([identity.key ?? "", identity.secret ?? "", identity.source, settings.keyModes[id], id === "zai-coding-cn" ? settings.zai : null, id === "commandcode" ? (account && account !== "default" ? account : "default") : null]);
+  const fingerprint = hash([identity.key ?? "", identity.secret ?? "", identity.source, settings.keyModes[id], id === "zai-coding-cn" ? settings.zai : null, id === "commandcode" ? (account && account !== "default" ? account : "default") : id === "openai-codex" ? identity.accountId ?? null : null]);
   if (this.fingerprints.has(cacheKey) && this.fingerprints.get(cacheKey) !== fingerprint) this.generations.set(cacheKey, (this.generations.get(cacheKey) ?? 0) + 1);
   this.fingerprints.set(cacheKey, fingerprint);
   const generation = this.generations.get(cacheKey) ?? 0;
@@ -1314,6 +1472,8 @@ export class SubUsageService extends TypertRemoteService {
      // 只输出真正有值的字段：视图里带 `undefined` 的键会被调用方的 schema 校验判成型别错误
      // （DSH 就会），而且「字段缺席」本来就该表示「这家没报告」，不是「报告了空」。
      ...(typeof entry.coverage === "string" ? { coverage: entry.coverage } : {}),
+      ...(typeof entry.availability === "string" ? { availability: entry.availability } : {}),
+      ...(typeof entry.availabilityReason === "string" ? { availabilityReason: entry.availabilityReason } : {}),
      ...(typeof entry.freshness === "string" ? { freshness: entry.freshness } : {}),
      ...(typeof entry.lastSuccessAt === "string" ? { lastSuccessAt: entry.lastSuccessAt } : {}),
       // 对外视图里不能出现内部凭据引用名：no-key 文案嵌了它，这里换成账户标签
@@ -1333,6 +1493,16 @@ export class SubUsageService extends TypertRemoteService {
   const unknownEntries = (query.unknown ?? []).map(id => ({ providerId: id, label: id, state: "error", errorCode: "subusage/unknown-provider", error: "本机运行中的 Host 版本较旧，不认识该提供商；重启 DSH 后生效", apiDetected: null, coverage: "partial", freshness: "unknown", keySource: "none", retryable: false, retainPrevious: false, windows: [], extras: [] }));
   const latest = this.load();
   if (hash(latest) !== hash(settings)) return this.result(latest, [...query.providerIds.map(id => ({ ...this.base(id, "none", latest, query.commandCodeAccount), state: "error", errorCode: "subusage/config-changed", error: "读取期间配置已改变，请刷新" })), ...unknownEntries]);
+  // Command Code 自动轮换：把轮换池健康摘要挂到默认账户（顶层 Key）entry 上。
+  // 仅当本次查询的就是默认账户（commandCodeAccount 为空）时——查某个额外账户时不挂，
+  // 那条 entry 代表的是被点名的账户本身。提供方插件未运行 / 固定账户时 pool 为 null，原样返回。
+  if (query.providerIds.includes("commandcode") && (!query.commandCodeAccount || query.commandCodeAccount === "default")) {
+   const ccIndex = entries.findIndex(e => e && e.providerId === "commandcode");
+   if (ccIndex >= 0) {
+    const pool = await this.commandCodePool(latest, query.force, entries[ccIndex]);
+    if (pool) entries[ccIndex] = { ...entries[ccIndex], accountPool: pool };
+   }
+  }
   return this.result(latest, [...entries, ...unknownEntries]);
  }
  startMimoLogin(request) { return this.login.start(parseLoginStart(request)); } getMimoLoginStatus() { return this.login.status(); }
@@ -1424,7 +1594,8 @@ function formatQuotaText(value) {
   if (entry.state !== "ok") return `${head}：${entry.error || "读取失败"}`;
   const parts = [];
   for (const window of entry.windows || []) {
-   parts.push(`${window.kind} ${window.status === "rate-limited" ? "已达限额" : `${Math.round(Math.max(0, 100 - window.percent) * 10) / 10}% 剩余`}${window.resetsAt ? `（重置 ${window.resetsAt}）` : ""}`);
+   const scope = window.budgetScope ? `${window.budgetScope} 预算` : ({ text: "文本/向量", "daily-capabilities": "日额度适用能力", all: "全部能力共享" }[window.detail?.scope] || window.groupLabel);
+   parts.push(`${scope ? scope + " · " : ""}${window.kind} ${window.status === "rate-limited" ? "已达限额" : `${Math.round(Math.max(0, 100 - window.percent) * 10) / 10}% 剩余`}${window.resetsAt ? `（重置 ${window.resetsAt}）` : ""}`);
   }
   // 账户名已经在标题行里了；再打一遍只会把额度挤出视野。
   // **只对多账户行跳过**（顶层 account 字段 = Command Code 的账户标注）：火山方舟的席位标注
@@ -1432,7 +1603,9 @@ function formatQuotaText(value) {
   // 信息，跟着一起丢就等于把额度说成不属于任何席位。
   const skipAccountExtra = typeof entry.account === "string" && entry.account !== "";
   for (const extra of entry.extras || []) { if (skipAccountExtra && extra.kind === "account") continue; parts.push(`${extra.kind}: ${extra.value}`); }
-  if (entry.freshness === "stale") parts.push("缓存数据");
+  const advice = { included: "接口仍允许订阅续用（基础额度可能已用尽）", paygo: "包含额度用尽时可按量续用，实际余额与服务端为准", blocked: "账户/预算受限或包含额度已用尽", unknown: "续用条件待确认，不保证可调用" };
+   if (advice[entry.availability]) parts.push(advice[entry.availability]);
+   if (entry.freshness === "stale") parts.push("缓存数据");
   return `${head}：${parts.length ? parts.join("；") : "暂无额度数据"}`;
  });
  // 一条额度都没读到时，末尾补一句汇总原因：模型据此才能告诉用户下一步做什么。
@@ -1467,7 +1640,8 @@ function hasQuotaData(entry) {
  if (!entry) return false;
  if (entry.state === "error") return true;
  if (entry.state !== "ok") return false;
- if (Array.isArray(entry.windows) && entry.windows.length) return true;
+ if (typeof entry.availability === "string") return true;
+  if (Array.isArray(entry.windows) && entry.windows.length) return true;
  const metadata = typeof entry.account === "string" && entry.account !== "" ? ["account", "plan"] : ["plan"];
  return (Array.isArray(entry.extras) ? entry.extras : []).some(item => !metadata.includes(item?.kind));
 }
@@ -1531,7 +1705,9 @@ function registerQuotaTool(ctx) {
            value: { type: "string", required: true }
           } }
          },
-         coverage: { type: "string", description: "complete | partial" },
+         coverage: { type: "string", description: "complete | partial — completeness of applicable reported quota facts, not a count of windows." },
+          availability: { type: "string", description: "Optional advisory: included | paygo | blocked | unknown. Window exhaustion alone need not block paid usage; absent means no separate billing-route evidence." },
+          availabilityReason: { type: "string", description: "Machine-readable basis for availability; no credentials or raw upstream objects." },
          freshness: { type: "string", description: "fresh | stale" },
          lastSuccessAt: { type: "string" },
          account: { type: "string", description: "Account label this entry reports (Command Code only, when the provider has several accounts)." },
@@ -1565,5 +1741,7 @@ function registerQuotaTool(ctx) {
   }));
  });
 }
-export { apply, inject, name };
+// IDS / PROVIDERS 仅供双端契约测试（test-contract.mjs）核对 Client 的 PROVIDER_META/PROVIDER_ORDER，
+// 防止新增厂商只改一端：漏改 Host 药丸取不到数、漏改 Client 则设置页与药丸缺项，且都不会报错。
+export { apply, inject, name, IDS, PROVIDERS };
 export default { name, inject, apply };