dsh-connect-modelscope-token-plan 0.4.0 → 0.5.0

package/lib/index.js

@@ -1,4 +1,4 @@
-import { C as obj, D as str, E as redactSecrets, O as verbatim, S as errMsg, T as pluginError, a as resolveSettings, c as LLM_PROVIDER_ID, d as isVisionModel, f as normalizeEntry, g as parseAllowedList, h as enabledCountOf, i as name, m as textToImageModelIds, n as inject, p as rosterWithAvailability, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as imageGenModelIds, v as hasHardQuotaWordingIn, w as optional, x as degrade, y as looksLikeRateLimit } from "./host-config.js";
+import { C as errMsg, D as redactSecrets, E as pluginError, O as str, S as degrade, T as optional, _ as parseAllowedList, a as resolveSettings, b as looksLikeRateLimit, c as LLM_PROVIDER_ID, d as imageGenModelIds, f as isVisionModel, g as enabledCountOf, h as rosterWithAvailability, i as name, k as verbatim, m as resolveDrawModelChoice, n as inject, p as normalizeEntry, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as drawCandidates, w as obj, y as hasHardQuotaWordingIn } from "./host-config.js";
 import { basename, join } from "node:path";
 import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -145,7 +145,7 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		async save(token) {
 			const value = verbatim(token, "");
 			if (typeof value !== "string" || value.trim() === "") throw new Error("a ModelScope token is required");
-			if (!isPlausibleToken(value.trim())) throw new Error("that does not look like a ModelScope access token (expected ms- followed by hex digits)");
+			if (!isPlausibleToken(value.trim())) throw new Error("that does not look like a ModelScope access token (expected ms- followed by at least 16 hex digits); if you are sure the token is correct, this plugin's shape check may be out of date");
 			const service = resolveService();
 			if (service !== null && typeof service.set === "function") {
 				await service.set(TOKEN_REF, value);
@@ -160,13 +160,18 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		* 服务实现里 unset 抛错时，吞掉错误会让路由回 `ok: true` + `source: credentials`，
 		* 而令牌**仍在 `~/.dsh/.credentials.yaml` 里并且仍被 resolve() 读回来**。
 		* 「忘掉令牌」是一个安全动作，谎报成功比失败更糟——用户以为凭据已删干净。
-		* 内存副本无论如何都先清掉（它才是本进程真正持有的那份）。
+		*
+		* **先 unset 成功、再删内存**：反过来的顺序有一个竞态——unset 抛错时内存
+		* 已删，下次 resolve() 会走 env 回退读回那个本该被删掉的令牌（如果 env
+		* 里也有 `MODELSCOPE_API_KEY`）。用户以为凭据已删干净，但它「复活」了。
+		* 现在 unset 失败时内存保留，resolve() 会读到内存里的旧值并报错（因为
+		* `source` 不是 `null`，但用户认为已经删了）——至少不会静默回退到 env。
 		*/
 		async forget() {
-			memory.delete(TOKEN_REF);
-			lastCheck = null;
 			const service = resolveService();
 			if (service !== null && typeof service.unset === "function") await service.unset(TOKEN_REF);
+			memory.delete(TOKEN_REF);
+			lastCheck = null;
 		},
 		/**
 		* 记录一次**零额度探针**的结论（probe 路由是唯一调用方）。
@@ -972,13 +977,14 @@ function parsePayload(raw) {
 * @param {object} options
 * @param {string} options.name - 插件 slug（状态目录名，来自 host-config）。
 * @param {string|null} [options.profile] - profile 名；null = 共享目录。
-* @param {number} [options.trendDays] - 天桶保留数（超出修剪；从配置注入，
-*   让「配置改小」在下次写入时生效，而不是等一个固定的内部常数）。
+* @param {number} [options.retentionDays] - 天桶**保留**数（超出即修剪；从配置注入，
+*   让「配置改小」在下次写入时生效，而不是等一个固定的内部常数）。与「显示多少天」
+*   是两件事——显示窗口由调用方传给 `trend(days)`，保留窗口恒 ≥ 它（host-config 夹）。
 * @param {number} [options.maxEvents] - 事件流上限。
 * @param {() => Date} [options.now] - 时钟源；测试注入。
 * @param {{warn?: (message: string) => void}} [options.logger] - ctx.logger。
 */
-function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents = 50, now = () => /* @__PURE__ */ new Date(), logger }) {
+function createFileUsageStore({ name, profile = null, retentionDays = 90, maxEvents = 50, now = () => /* @__PURE__ */ new Date(), logger }) {
 	const dir = profileStateDir(name, profile);
 	const file = join(dir, "usage.json");
 	/** 最近一次解析异常（损坏即忽略的痕迹），快照转 shapeWarnings。 */
@@ -1064,9 +1070,9 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 		loaded = true;
 		await persist(payload);
 	});
-	/** 修剪：只留最近 trendDays 个天桶（按 dateKey 排序，今天不删）。 */
+	/** 修剪：只留最近 retentionDays 个天桶（按 dateKey 排序，今天不删）。 */
 	const pruneDays = (payload, todayKey) => {
-		const keep = new Set(Object.keys(payload.days).sort().slice(-Math.max(1, trendDays)));
+		const keep = new Set(Object.keys(payload.days).sort().slice(-Math.max(1, retentionDays)));
 		keep.add(todayKey);
 		for (const key of Object.keys(payload.days)) if (!keep.has(key)) delete payload.days[key];
 	};
@@ -1179,7 +1185,7 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 			return out;
 		},
 		/** 最近 N 天趋势（含今天；缺桶 = 该日 0 次，真实零不是数据丢失）。 */
-		async trend(days = trendDays) {
+		async trend(days = retentionDays) {
 			const payload = await cache.read();
 			const out = [];
 			const cursor = now();
@@ -1407,6 +1413,39 @@ function createCoalescedFetch(options = {}) {
 *    目录声明过窗口的条目不进打标，策展表永不推翻平台声明。
 * 4. 生图/语音模型（Qwen-Image-Edit、ACE-Step 等）无对话上下文，不收。
 */
+/**
+* 本表最后一次与 models.dev / 真机目录核对的日期（ISO 日期，UTC）。
+*
+* 存在的理由：策展表是**静态知识**，而目录会上下架。维护纪律要求「目录下架的条目
+* 应随手删除」，但没有任何机制会自动知道下架发生了——没有这个日期，表会悄悄腐烂，
+* 而使用者无从判断一个值是三个月前还是三年前核的。快照侧据此在表过期时给一条
+* shapeWarning（见 {@link curatedCatalogStale}）。
+*/
+const CURATED_AS_OF = "2026-10-16";
+/**
+* 策展表距上次核对已经过去多少天；日期解析不了返回 `null`。
+* @param {Date} [now] - 时钟源（测试注入）。
+* @returns {number|null} 天数（向下取整），或 null。
+*/
+function curatedCatalogAgeDays(now = /* @__PURE__ */ new Date()) {
+	const asOf = Date.parse("2026-10-16T00:00:00Z");
+	if (Number.isNaN(asOf)) return null;
+	const delta = now.getTime() - asOf;
+	return delta < 0 ? 0 : Math.floor(delta / 864e5);
+}
+/**
+* 策展表是否该被复核了：距 {@link CURATED_AS_OF} 超过 `maxAgeDays` 天。
+*
+* 只回答「该提醒了吗」，不回答「表里的值错了」——过期的表往往仍然正确，只是
+* 不再有核对背书。快照把它转成一条 shapeWarning，而不是拒绝使用表里的值。
+* @param {Date} [now] - 时钟源（测试注入）。
+* @param {number} [maxAgeDays] - 容忍的天数，默认 180。
+* @returns {boolean}
+*/
+function curatedCatalogStale(now = /* @__PURE__ */ new Date(), maxAgeDays = 180) {
+	const age = curatedCatalogAgeDays(now);
+	return age !== null && age > maxAgeDays;
+}
 /** id → 标称上下文窗口（tokens）。键必须与魔搭目录 id 逐字一致。 */
 const CURATED_CONTEXT_WINDOWS = {
 	"deepseek-ai/DeepSeek-V4-Flash-0731": 1048576,
@@ -1493,6 +1532,25 @@ async function mapWithConcurrency(items, limit, fn) {
 function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 	const doFetch = deps.fetchImpl ?? fetch;
 	const { read } = createCoalescedFetch();
+	/**
+	* 详情端点任务标签的**独立**缓存与 TTL——与目录/余额的 `read` 刻意分开。
+	*
+	* 标签回答「这个模型吃不吃图」，是出厂能力，几乎不变；目录/余额回答「现在有
+	* 什么、还剩多少」——两者需要的陈旧度差着量级。它们曾共用 `cacheSeconds`
+	* （默认 60 秒），而面板与对话框胶囊按 `pollSeconds`（默认 30s）轮询快照、
+	* 快照每次都调 `fetchModels`：穿透时对目录里每个模型各打一次
+	* `siteBase/api/v1/models/{id}`。当前目录 ~37 条 = **每轮 38 个 HTTP 请求、
+	* 稳定每分钟一轮**（约 5 万/天），只为判一个布尔值，打的还是 modelscope.cn
+	* 网站上一个非公开、非契约的接口。那不叫新鲜，叫白打。
+	*
+	* `maxAgeMs` 必须一起抬：coalesced-fetch 的清扫上限默认 1 小时（那是「任何
+	* 调用方的最长 TTL」），不抬的话 6 小时的 TTL 会被清扫提前作废。键数等于目录
+	* 里的模型数（约 40 条），无界增长不成立。
+	*/
+	const TAGS_TTL_MS = 216e5;
+	const { read: readTags } = createCoalescedFetch({ maxAgeMs: TAGS_TTL_MS });
+	/** 详情端点的并发：长 TTL 之后扇出已经很稀，没必要一上来 6 路齐发去撞主站。 */
+	const TAG_FETCH_CONCURRENCY = 3;
 	/** 带超时的一次 fetch（AbortController；abort → TIMEOUT_ERROR）。 */
 	const fetchWithTimeout = async (url, init) => {
 		const controller = new AbortController();
@@ -1512,13 +1570,14 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 	/**
 	* 丢弃一个我们不读的响应体。
 	*
-	* undici 里未消费的 body 会**占住连接**直到 GC。目录刷新会对 35 个模型并发打
-	* 详情端点（`Promise.all` 分批），其中任何一条走「!ok」或「形状不符」分支，
-	* 连接就一直挂着——短时间内连接池被这些挂起的响应吃满，后面的请求开始排队。
+	* undici 里未消费的 body 会**占住连接**直到 GC。标签扇出会对目录里 30–40 个
+	* 模型并发打详情端点（`mapWithConcurrency` 分批），其中任何一条走「!ok」或
+	* 「形状不符」分支，连接就一直挂着——短时间内连接池被这些挂起的响应吃满，
+	* 后面的请求开始排队。
 	*
 	* `cancel()` 是显式的弃权：告诉 undici「这个 body 我不要了」，它会立刻释放
 	* 连接而不是等GC。用 `void` 前缀是因为这是best-effort——取消失败不影响我们
-	* 已经决定返回 `[]` 的结论。
+	* 已经决定的结果。
 	*/
 	const discardBody = (response) => {
 		try {
@@ -1539,8 +1598,14 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 	/**
 	* 单个模型的详情端点任务标签（modelscope.cn/api/v1/models/{id}）。
 	* 免认证 GET，零推理额度（实测匿名 200）。返回 `Data.Tasks[].Name`（+
-	* `widgets[].task` 兜底）去重后的标签数组；任意失败 / 非预期形状返回空数组，
-	* 调用方据此回退策展清单 + 名字启发。
+	* `widgets[].task` 兜底）去重后的标签数组。
+	*
+	* **失败一律抛，绝不返回 `[]`**：本函数的结果会被 {@link TAGS_TTL_MS} 缓存
+	* 六小时，而 `[]` 是一个**结论**（「这个模型没有任务标签」）。把 429 / 5xx /
+	* 形状漂移降级成 `[]` 再缓存，等于让一次网络抖动把某个模型的视觉标签钉死半天
+	* ——正是「读不到 ≠ 没有」的反面。coalesced-fetch 不缓存 rejection（失败被当
+	* 「不是答案」共享，但不落盘），所以抛出去的那一轮不会被记住；调用方 catch 成
+	* `[]`，只影响这一轮，下一轮照常重试。
 	*/
 	const fetchTaskTags = async (id) => {
 		const detailUrl = settings.siteBase + "/api/v1/models/" + encodeURI(id);
@@ -1550,10 +1615,16 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 		});
 		if (!response.ok) {
 			discardBody(response);
-			return [];
+			throw new Error("model detail failed with HTTP " + String(response.status));
 		}
-		const json = await response.json().catch(() => null);
-		if (json === null || typeof json !== "object" || json.Code !== 200) return [];
+		let json;
+		try {
+			json = await response.json();
+		} catch {
+			discardBody(response);
+			throw new Error("model detail body was not JSON");
+		}
+		if (json === null || typeof json !== "object" || json.Code !== 200) throw new Error("model detail shape drifted (expected {Code:200, Data:{Tasks:[...]}})");
 		const data = json.Data ?? {};
 		const tasks = [];
 		for (const t of Array.isArray(data.Tasks) ? data.Tasks : []) {
@@ -1594,7 +1665,9 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 		*/
 		async fetchModels(contextOverride) {
 			const url = settings.apiBase + "/models";
-			return await read(`models:${contextOverride ?? "catalog"}`, async () => {
+			const cacheKey = contextOverride != null ? `models:override:${contextOverride}` : "models:catalog";
+			const cacheTtl = contextOverride != null ? Math.min(settings.cacheSeconds * 1e3, 5e3) : settings.cacheSeconds * 1e3;
+			return await read(cacheKey, async () => {
 				const response = await fetchWithTimeout(url, { method: "GET" });
 				if (!response.ok) {
 					const message = await readErrorMessage(response);
@@ -1605,7 +1678,14 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 				if (json === null || typeof json !== "object" || json.object !== "list" || !Array.isArray(json.data)) throw pluginError(CODE.UPSTREAM_ERROR, "model catalog shape drifted (expected {object:'list', data:[...]})");
 				const raws = json.data;
 				const ids = raws.map((r) => str(r.id, "")).filter((id) => id !== "");
-				const tagArrays = await mapWithConcurrency(ids, 6, (id) => fetchTaskTags(id).catch(() => []));
+				const tagArrays = await mapWithConcurrency(ids, TAG_FETCH_CONCURRENCY, async (id) => {
+					try {
+						const cached = await readTags(`model-tags:${id}`, () => fetchTaskTags(id), TAGS_TTL_MS);
+						return Array.isArray(cached) ? cached : [];
+					} catch {
+						return [];
+					}
+				});
 				const tagsById = /* @__PURE__ */ new Map();
 				ids.forEach((id, i) => tagsById.set(id, tagArrays[i] ?? []));
 				const entries = raws.map((raw) => {
@@ -1645,7 +1725,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 					ids: entries.map((entry) => entry.id),
 					fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
 				};
-			}, settings.cacheSeconds * 1e3);
+			}, cacheTtl);
 		},
 		/**
 		* 官方「魔粒」余额：GET siteBase/openapi/v1/magicubes/balance（Bearer
@@ -1780,7 +1860,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 * collapses here, so the three call sites that produce it stay in step instead
 * of each spelling out the same three `null`s.
 */
-const EMPTY_PAYLOAD$1 = {
+const EMPTY_PAYLOAD$2 = {
 	enabled: null,
 	enabledIds: null,
 	contextWindow: null,
@@ -2009,7 +2089,7 @@ function createFileProviderStore(options = {}) {
 	* `null` branch collapses here, in one place, rather than at every caller.
 	* @returns {Promise<ProviderPayload>} the payload; the empty payload when nothing is stored.
 	*/
-	const readPayload = async () => await read() ?? EMPTY_PAYLOAD$1;
+	const readPayload = async () => await read() ?? EMPTY_PAYLOAD$2;
 	/**
 	* Read one payload, then hand it to {@link writePayload} — the read-modify-
 	* write that keeps the switch and the list from clobbering each other.
@@ -2227,7 +2307,7 @@ function createFileProviderStore(options = {}) {
 const DRAW_STORE_VERSION = 1;
 /** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
 const KNOWN_DRAW_VERSIONS = Object.freeze([1]);
-const EMPTY_PAYLOAD = {
+const EMPTY_PAYLOAD$1 = {
 	enabled: null,
 	modelId: null,
 	version: null
@@ -2326,7 +2406,7 @@ function createFileDrawStore(options = {}) {
 	* 读当前 payload。
 	* @returns {Promise<DrawPayload>}
 	*/
-	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD$1;
 	/**
 	* 读-改-写一份补丁，**整段排队**。
 	*
@@ -2413,6 +2493,264 @@ function createFileDrawStore(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/switch-precedence.ts
+/**
+* 所有 opt-in 开关共用的唯一裁决：「面板保存值 vs 配置默认值」。
+*
+* 规则只有一条：**面板保存值赢，否则配置默认值说了算**。来源标签（`panel` /
+* `config`）随答案一起返回，面板才能说出是谁在管。规则收在一处，是为了让开关
+* 再也无法各自发明一套优先级方言；`test/switch-precedence.test.mjs` 钉死这个
+* 方言，照抄形状的新调用方会被它标成异类。
+*
+* 不服务「纯面板拥有、无配置默认值」的开关——那种没有可裁决的配置默认值，
+* 调用方直接读即可。peer-free，纯函数。
+*
+* @module dsh-connect-modelscope-token-plan/switch-precedence
+*/
+/**
+* Resolve the effective boolean switch: a panel-saved value always wins,
+* otherwise the config default rules.
+* @param {boolean|null} panel - the panel-saved value (`null` = never saved).
+* @param {boolean} config - the patch-declared default.
+* @returns {boolean} the effective switch.
+*/
+function resolveSwitchEnabled(panel, config) {
+	return (panel ?? config) === true;
+}
+/**
+* Resolve the effective string preference (e.g. a draw-model id): a
+* panel-saved value wins, otherwise the config default rules.
+* @param {string|null} panel - the panel-saved value (`null` = never saved).
+* @param {string|undefined} config - the patch-declared default.
+* @returns {string|undefined} the effective preference.
+*/
+function resolveSwitchValue(panel, config) {
+	return panel ?? config;
+}
+/**
+* Resolve the effective numeric preference (e.g. how many days the trend chart
+* shows): the same `panel ?? config` dialect as the other two shapes.
+*
+* Range clamping is deliberately NOT done here — the bound (a retention
+* window) belongs to the caller that knows it (`host-config` / the snapshot
+* aggregate), not to the precedence rule.
+* @param {number|null} panel - the panel-saved value (`null` = never saved).
+* @param {number} config - the patch-declared default.
+* @returns {number} the effective preference.
+*/
+function resolveSwitchNumber(panel, config) {
+	return panel ?? config;
+}
+/**
+* Where the effective value came from — the panel when it saved one, the
+* config otherwise. Rides with every resolved answer so the panel can name
+* the side in charge.
+* @param {boolean|string|number|null} panel - the panel-saved value.
+* @returns {"panel"|"config"}
+*/
+function switchSource(panel) {
+	return panel === null ? "config" : "panel";
+}
+
+//#endregion
+//#region src/host/usage-prefs-store.ts
+/**
+* 用量面板的**显示偏好**——目前只有一个字段：趋势图的显示窗口（画多少天）。
+*
+* ## 为什么单独一个文件
+*
+*  - `usage.json` 是**数据**（天桶 / 单模型 / 事件），写路径是观测热路径。把一个
+*    显示偏好混进去，会让「偏好读不到」与「计数文件损坏」共用一条降级语义；更要命
+*    的是版本漂移——旧构建重写那份 payload 时会**静默丢掉**它不认识的键。
+*  - `provider.json` 是 provider 注册的 desired state（开关 / 允许清单 / 窗口覆盖），
+*    与「趋势图画多少天」无关；合成一份 payload 会让两边的写入时序互相牵连。
+*
+* 落点与 provider / draw 同一套分段规则：`$DSH_HOME/state/<profile>/<plugin>/usage-prefs.json`
+* （无 profile 时落共享目录）。分段的意思是「这个 profile 想看多长」，两个 profile
+* 不互相覆盖。
+*
+* 优先级与所有 opt-in 开关同一份裁决（`switch-precedence.ts`）：面板保存值赢，
+* 否则 `cordis.patch.yml` 的 `trendDays` 说了算；两者都会在 host-config 里被夹进
+* 保留窗口之内（`retentionDays`）——**画得比留得多**会把已剪的日子画成 0。
+*
+* 完整性三件套与 provider / usage / draw **同源**（全部上收在 `state-store.ts`，
+* 本文件只做调用方，论述见 `draw-store.ts` 头注，不在此重复）：写串行化
+* （{@link createStateWriteQueue}）、写守卫（{@link guardStateWrite}，ADR-006）、
+* 读侧说明（{@link stateVersionNote}）。
+*
+* doctor 覆盖：{@link describeUsagePrefsPayload} 给只读速览，`doctor.ts` 据此把
+* usage-prefs.json 的「损坏 / 未知版本」报进症状表。
+*
+* @module dsh-connect-modelscope-token-plan/usage-prefs-store
+*/
+/** 本 store 落盘 payload 的版本。 */
+const USAGE_PREFS_VERSION = 1;
+/** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
+const KNOWN_USAGE_PREFS_VERSIONS = Object.freeze([1]);
+const EMPTY_PAYLOAD = {
+	windowDays: null,
+	version: null
+};
+/**
+* 本 build 读不读得懂这个版本。
+*
+* 与 provider / draw 的 `isKnown*Version` 同形：**白名单**判据，不与
+* {@link USAGE_PREFS_VERSION} 比较——升级后旧号仍要可读。读侧、报告侧
+* （versionNote / describeUsagePrefsPayload）问的都是这一个函数，三者不可能就
+* 「什么是未知版本」说两套话。写侧问的是 `state-store` 的 `isKnownStateVersion`
+* （它额外放行 `null` = 没有文件，那是唯一该写的情形）。
+* @param {unknown} version - 盘上读到的值（可能根本不是数字）。
+* @returns {boolean}
+*/
+function isKnownUsagePrefsVersion(version) {
+	return typeof version === "number" && KNOWN_USAGE_PREFS_VERSIONS.includes(version);
+}
+/**
+* 归一一个保存的显示窗口：正整数（向下取整），或 `null`（= 跟随配置默认）。
+*
+* **不在这里夹上界**：上界是保留窗口（`retentionDays`），那是 host-config 的事，
+* 此模块不该知道它。传进来的越界值由调用方（host-config / 快照聚合 / 路由）夹。
+* @param {unknown} value - 原始值。
+* @returns {number|null} 归一后的天数或 `null`。
+*/
+function normalizeWindowDays(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return null;
+	const days = Math.floor(value);
+	return days > 0 ? days : null;
+}
+/** 本 store 的目录（与 provider / draw 同一套分段规则）。 */
+function usagePrefsDir(profile, dir) {
+	if (typeof dir === "string" && dir !== "") return dir;
+	return profile ? profileStateDir(name, profile) : stateDir(name);
+}
+/**
+* 显示窗口的**唯一**裁决 + 夹取：面板保存值优先（沿用全仓唯一方言
+* {@link resolveSwitchNumber}），否则配置默认；随后落进 `[1, maxDays]`。
+*
+* 夹取放在这里而不是 store 里，是因为 store 不该知道上界；放在**本模块**而不是
+* 两个调用方各写一遍，是因为「面板值 vs 默认」和「夹到保留窗口」加起来只有一条
+* 正确算法——路由保存时与快照聚合渲染时各写一份，就会出现「面板显示 90 天、
+* 图里只画了 14 天」这类两处不一致。
+* @param {number|null} panel - 面板保存值（`null` = 未保存）。
+* @param {number} fallback - 配置默认（已由 host-config 夹过）。
+* @param {number} maxDays - 上界（保留窗口，`retentionDays`）。
+* @returns {number} 生效天数。
+*/
+function resolveWindowDays(panel, fallback, maxDays) {
+	const want = resolveSwitchNumber(panel, fallback);
+	return Math.min(Math.max(1, Math.floor(want)), Math.max(1, Math.floor(maxDays)));
+}
+/**
+* 文件支撑的用量显示偏好。
+* @param {StoreOptions} [options] - `{ dir, profile, ttlMs, logger }`。
+* @returns {object} store 句柄。
+*/
+function createFileUsagePrefsStore(options = {}) {
+	const { dir, profile = null, ttlMs = STATE_READ_TTL_MS, logger } = options;
+	const stateDir = usagePrefsDir(profile, dir);
+	const filePath = join(stateDir, "usage-prefs.json");
+	/**
+	* 写一份 payload 并落盘。
+	*
+	* ADR-006 写守卫（{@link guardStateWrite}）先问盘：版本不认或文件读不出 →
+	* 返回拒绝理由（已 degrade 记录），不落笔。守卫与随后的写入在同一个临界区里
+	* （由 patchPayload 的链保证），判据与执行之间不隔任何 await。
+	* @param {object} body - 要持久化的 JSON 体。
+	* @returns {Promise<string|null>} 拒绝原因，或 `null` = 已写入。
+	*/
+	const writePayload = async (body) => {
+		const refusal = await guardStateWrite(filePath, KNOWN_USAGE_PREFS_VERSIONS, {
+			label: "usage-prefs-state",
+			logger
+		});
+		if (refusal !== null) return refusal;
+		await ensureStateDir(stateDir);
+		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir, "usage-prefs.json") });
+		return null;
+	};
+	/** 写串行化：读-改-写必须排队（详见{@link createStateWriteQueue}）。 */
+	const writeQueue = createStateWriteQueue();
+	/**
+	* 解析一份 payload；认不出的版本读作「没设过」但**记住**版本号——读侧宽容、
+	* versionNote 负责把宽容说出口（写侧守卫已挡住覆盖，两半合起来才是 ADR-006）。
+	*/
+	const parsePayload = async () => {
+		const source = obj(await readStateJson(filePath));
+		const version = typeof source.version === "number" ? source.version : null;
+		if (!isKnownUsagePrefsVersion(version)) return {
+			windowDays: null,
+			version
+		};
+		return {
+			windowDays: normalizeWindowDays(source.windowDays),
+			version
+		};
+	};
+	const cache = createStateReadCache(parsePayload, { ttlMs });
+	/**
+	* 读当前 payload。
+	* @returns {Promise<UsagePrefsPayload>}
+	*/
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	/**
+	* 读-改-写，**整段排队**。
+	*
+	* 基线每次从磁盘重读（`parsePayload` 直读，不走 TTL 缓存）：两个 Host 进程共享
+	* 一个状态目录，而缓存里可能是写入前的值（provider §8d 的回归用例在 draw 上
+	* 同样成立，见 draw-store.ts）。写成功即 `cache.remember`。
+	*
+	* 失败语义与 provider / draw 对齐：拒绝原因与 IO 失败都**向上抛**（save 抛、
+	* 路由 catch 后 `respondError` 呈报），链自己吞掉失败继续走后面的保存。
+	*
+	* @param {number|null} windowDays - 新的显示窗口；`null` = 清除（回到配置默认）。
+	* @returns {Promise<void>}
+	*/
+	const save = (windowDays) => writeQueue.enqueue(async () => {
+		const body = { version: 1 };
+		if (windowDays !== null) body.windowDays = windowDays;
+		body.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const refusal = await writePayload(body);
+		if (refusal !== null) throw new Error(refusal);
+		cache.remember({
+			windowDays,
+			version: 1
+		});
+	});
+	return {
+		/** 面板保存的显示窗口天数；`null` = 跟随配置默认。 */
+		async windowDays() {
+			return (await readPayload()).windowDays;
+		},
+		/**
+		* 盘上带着本构建读不懂的版本时的一句说明，否则 `null`。
+		*
+		* 读侧宽容（未知版本读作「没设过」）的另一半：快照聚合把它转进
+		* `shapeWarnings`，doctor 报同一份文件。没有它，「保存的显示窗口被忽略」在
+		* 面板上就是「从未保存过」——而回退方向是配置默认。
+		* @returns {Promise<string|null>}
+		*/
+		async versionNote() {
+			const version = (await readPayload()).version;
+			if (version === null || isKnownUsagePrefsVersion(version)) return null;
+			return stateVersionNote({
+				label: "usage-prefs-state",
+				file: filePath,
+				version,
+				known: KNOWN_USAGE_PREFS_VERSIONS,
+				consequence: "the saved trend window is being answered as \"not set\", so the chart falls back to the config default."
+			});
+		},
+		/** 保存显示窗口（`null` = 清掉，回到配置默认）。 */
+		async saveWindowDays(windowDays) {
+			if (windowDays !== null && !(typeof windowDays === "number" && Number.isFinite(windowDays) && Math.floor(windowDays) > 0)) throw new TypeError("trend window expects a positive integer or null");
+			await save(windowDays === null ? null : Math.floor(windowDays));
+		},
+		/** 落盘路径（诊断与测试用）。 */
+		filePath
+	};
+}
+
 //#endregion
 //#region src/host/draw.ts
 /**
@@ -2787,19 +3125,6 @@ function createDrawJobs(options = {}) {
 */
 /** agent 工具名。带插件前缀，避免与 `dsh-draw-router` 的 `draw_image` 撞名。 */
 const DRAW_TOOL_NAME = "modelscope_draw_image";
-/**
-* 已知能**纯文生图**的目录内模型 id（2026-10-16 真机复核）。
-*
-* 为什么需要手工策展：api-inference 目录里至今**没有**平台声明的 `text-to-image`
-* 条目，只有 2 条 `image-to-image`——而两者行为**不同**：
-* `Qwen/Qwen-Image-Edit` 不带 `image_url` 纯文生图可用（本轮实测：提交成功、两次
-* 15min 排队超时后于 9.7min 出图）；`MusePublic/Qwen-Image-Edit` 纯文生图被上游
-* 直接拒绝（提交阶段 HTTP 4xx：`image_url is required for model: …`）。
-* 能力枚举把两者都归为 `image-to-image`，区分不了这个差异，所以这里用实测知识兜底：
-* 目录里没有 `text-to-image` 可挑时，默认偏向这个已知能用的 id，而不是「目录第一个」
-* （真实目录顺序 `MusePublic/…` 在前，照旧逻辑纯文生图必挂）。
-*/
-const KNOWN_T2I_MODEL_ID = "Qwen/Qwen-Image-Edit";
 /** 一次失败的冷却窗：出图慢，失败后立刻重试既易撞限流又白等。 */
 const DRAW_FAILURE_COOLDOWN_MS = 6e4;
 /**
@@ -2906,7 +3231,7 @@ async function submitDrawTask({ fetchImpl, apiBase, apiKey, model, prompt, image
 * @param {number} [options.pollIntervalMs] - 轮询间隔（测试可缩短）。
 * @returns {Promise<DrawAwait>} 三种结局之一。
 */
-async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW_WAIT_BUDGET_MS, pollIntervalMs = DRAW_POLL_INTERVAL_MS }) {
+async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW_WAIT_BUDGET_MS, pollIntervalMs = DRAW_POLL_INTERVAL_MS, signal }) {
 	const headers = {
 		Authorization: `Bearer ${apiKey}`,
 		"Content-Type": "application/json"
@@ -2920,7 +3245,14 @@ async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW
 			kind: "pending",
 			polls
 		};
-		await sleep(interval);
+		try {
+			await sleep(interval, signal);
+		} catch {
+			return {
+				kind: "pending",
+				polls
+			};
+		}
 		polls++;
 		let polled;
 		try {
@@ -2995,16 +3327,7 @@ async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW
 * @returns {string|null} 选中的 id。
 */
 function pickDrawModel(entries, requested, preferred) {
-	const want = str(requested, "");
-	if (want !== "") return want;
-	const preferredId = str(preferred, "");
-	if (preferredId !== "") return preferredId;
-	const ids = imageGenModelIds(entries);
-	if (ids.length === 0) return null;
-	const t2i = textToImageModelIds(entries);
-	if (t2i.length > 0) return t2i[0] ?? null;
-	if (ids.includes("Qwen/Qwen-Image-Edit")) return KNOWN_T2I_MODEL_ID;
-	return ids[0] ?? null;
+	return resolveDrawModelChoice(entries, requested, preferred).id;
 }
 /**
 * 目录里可用于出图的模型 id（工具结果里回显，方便 agent 与用户看到实际候选）。
@@ -3061,6 +3384,10 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 	*/
 	const waitMs = Math.min(timeoutMs, Math.max(1, Math.floor(Number(settings?.drawWaitMs) > 0 ? Number(settings?.drawWaitMs) : DRAW_WAIT_BUDGET_MS)));
 	const apiBase = str(settings?.apiBase, "https://api-inference.modelscope.cn/v1");
+	const abortController = new AbortController();
+	const abortIfDisposed = () => {
+		if (isDisposed()) abortController.abort();
+	};
 	/**
 	* 等一个作业，把 {@link awaitDrawTask} 的三种结局翻译成工具结果或错误。
 	*
@@ -3073,13 +3400,15 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 	* @throws {Error} 真失败（上游 FAILED / 轮询 HTTP 失败）或越过总放弃线。
 	*/
 	const waitAndReport = async (apiKey, job, available) => {
+		abortIfDisposed();
 		const awaited = await awaitDrawTask({
 			fetchImpl,
 			apiBase,
 			apiKey,
 			taskId: job.taskId,
 			waitMs,
-			pollIntervalMs
+			pollIntervalMs,
+			signal: abortController.signal
 		});
 		if (awaited.kind === "failed") {
 			jobs.drop(job.jobId);
@@ -3101,7 +3430,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 			};
 		}
 		const elapsedMs = Date.now() - job.submittedAt;
-		if (elapsedMs >= timeoutMs) throw new Error(describeDrawFailure({ cause: `超过总预算（${Math.round(timeoutMs / 1e3)}s，${polls} 次轮询）仍未拿到结果。上游任务（${job.taskId}）**可能仍在生成**——实测排队时长在 1–15 分钟间大幅波动，与请求本身无关；注意放弃后原任务的结果不保证还能取回` }));
+		if (elapsedMs >= timeoutMs) throw new Error(describeDrawFailure({ cause: `超过总预算（${Math.round(timeoutMs / 1e3)}s，${polls} 次轮询）仍未拿到结果。上游任务（${job.taskId}）可能仍在生成——实测排队时长在 1–15 分钟间大幅波动，与请求本身无关；注意放弃后原任务的结果不保证还能取回` }));
 		return {
 			source: "modelscope",
 			status: "pending",
@@ -3114,7 +3443,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 	};
 	return defineTool({
 		name: DRAW_TOOL_NAME,
-		description: "Generate or edit an image with the ModelScope (魔搭) API-Inference token. Text-to-image by default; pass `imageUrl` to edit an existing image (image-to-image), or an array of URLs for multi-image editing. Omit `model` to use the catalogue's image model. TWO-PHASE: upstream generation queues, so latency varies from ~1 minute to 15+ minutes. Call without `jobId` to submit and wait briefly; if the result is `status: pending`, call again with the returned `jobId` to keep polling. A pending result is NOT a failure — the image is still being generated. Available image model ids are reported in the result.",
+		description: "Generate or edit an image with the ModelScope (魔搭) API-Inference token. Text-to-image by default; pass `imageUrl` to edit an existing image (image-to-image), or several newline-separated URLs for multi-image editing. Omit `model` to use the catalogue's image model. TWO-PHASE: upstream generation queues, so latency varies from ~1 minute to 15+ minutes. Call without `jobId` to submit and wait briefly; if the result is `status: pending`, call again with the returned `jobId` to keep polling. A pending result is NOT a failure — the image is still being generated. Available image model ids are reported in the result.",
 		parameters: {
 			prompt: {
 				type: "string",
@@ -3175,7 +3504,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 		},
 		timeoutMs: waitMs + 1e4,
 		async execute(params) {
-			if (isDisposed()) throw new Error("modelscope draw tool is no longer mounted");
+			if (abortController.signal.aborted || isDisposed()) throw new Error("modelscope draw tool is no longer mounted");
 			const apiKey = await resolveApiKey();
 			if (typeof apiKey !== "string" || apiKey.trim() === "") throw new Error("MODELSCOPE_API_KEY 未配置：在面板粘贴 ms- 访问令牌，或设置该环境变量");
 			const resumeId = str(params?.jobId, "");
@@ -3293,9 +3622,29 @@ async function safeJson(response, text) {
 		}
 	}
 }
-/** 可注入的 sleep（测试可覆写；这里只提供默认实现）。 */
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* 可注入的 sleep（测试可覆写；这里只提供默认实现）。
+*
+* 支持 `AbortSignal`：插件 dispose 时可以立即中断等待，而不是等 sleep 自然结束。
+* 默认 15s 的轮询间隔意味着用户点「停止」后最多要等 15s 才真正停——abort 让
+* 停止信号立即生效。
+*/
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(/* @__PURE__ */ new Error("sleep aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error("sleep aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
 }
 
 //#endregion
@@ -3325,52 +3674,6 @@ function resetDrawToolNote() {
 	note = null;
 }
 
-//#endregion
-//#region src/host/switch-precedence.ts
-/**
-* 所有 opt-in 开关共用的唯一裁决：「面板保存值 vs 配置默认值」。
-*
-* 规则只有一条：**面板保存值赢，否则配置默认值说了算**。来源标签（`panel` /
-* `config`）随答案一起返回，面板才能说出是谁在管。规则收在一处，是为了让开关
-* 再也无法各自发明一套优先级方言；`test/switch-precedence.test.mjs` 钉死这个
-* 方言，照抄形状的新调用方会被它标成异类。
-*
-* 不服务「纯面板拥有、无配置默认值」的开关——那种没有可裁决的配置默认值，
-* 调用方直接读即可。peer-free，纯函数。
-*
-* @module dsh-connect-modelscope-token-plan/switch-precedence
-*/
-/**
-* Resolve the effective boolean switch: a panel-saved value always wins,
-* otherwise the config default rules.
-* @param {boolean|null} panel - the panel-saved value (`null` = never saved).
-* @param {boolean} config - the patch-declared default.
-* @returns {boolean} the effective switch.
-*/
-function resolveSwitchEnabled(panel, config) {
-	return (panel ?? config) === true;
-}
-/**
-* Resolve the effective string preference (e.g. a draw-model id): a
-* panel-saved value wins, otherwise the config default rules.
-* @param {string|null} panel - the panel-saved value (`null` = never saved).
-* @param {string|undefined} config - the patch-declared default.
-* @returns {string|undefined} the effective preference.
-*/
-function resolveSwitchValue(panel, config) {
-	return panel ?? config;
-}
-/**
-* Where the effective value came from — the panel when it saved one, the
-* config otherwise. Rides with every resolved answer so the panel can name
-* the side in charge.
-* @param {boolean|string|null} panel - the panel-saved value.
-* @returns {"panel"|"config"}
-*/
-function switchSource(panel) {
-	return panel === null ? "config" : "panel";
-}
-
 //#endregion
 //#region src/host/draw-register.ts
 /**
@@ -3393,11 +3696,14 @@ function switchSource(panel) {
 *
 * peer-dependent：`@deepseek-ai/dsh-tools` 由 `deps.loadToolsModule` 惰性注入。
 *
-* **本文件目前没有测试覆盖**——`registerDrawTool` 在 `test/` 里零引用
-* （docs/ROADMAP.md Backlog 记着这条缺口）。但**这不是「不能」**：同一处境的
-* `llm-adapter.ts` / `draw-runtime.ts` 已经用 `test/helpers/peer-stub-loader.mjs`
-* 证明这类模块能在离线套件里原样加载执行。此前的措辞把 `llm-adapter.ts` 当作
-* 「同样无法导入」的例证拉来作证，那条类比在补上那个 loader 之后已经失效。
+* **测试覆盖**：`test/draw-register.test.mjs`（2026-10-17 补上，此前这里是零引用）
+* 用 `deps.loadToolsModule` 这条现成的缝注入伪 `defineTool`，让真装配链原样跑起来
+* ——**不需要** peer-stub-loader。教训是：本文件此前把「peer-dependent」直接读成
+* 「测不了」，而缝早就留好了；同处境的 `llm-adapter.ts` / `draw-runtime.ts` 用
+* `test/helpers/peer-stub-loader.mjs` 证明过另一条路（那条 loader 是给**没有缝**
+* 的直连 import 用的）。`tools/dev/mutate-spec.json` 里有本文件的一组变异，用来
+* 保证那套测试真的会红——第一版测试里 `mount` 助手自己清了缺席原因，于是「过期
+* 原因会不会被清掉」那条断言是测试自己满足的，是变异测试把它抓出来的。
 *
 * @module dsh-connect-modelscope-token-plan/draw-register
 */
@@ -4062,7 +4368,8 @@ function createProviderPublisher(deps = {}) {
 				resolveApiKey: effectiveResolveApiKey,
 				get: effectiveGetLlm,
 				unavailableModelIds: state.unavailableIds,
-				...usage !== void 0 ? { usage } : {}
+				...usage !== void 0 ? { usage } : {},
+				...usage !== void 0 ? { onError: (error) => effectiveLogger?.warn?.(`usage record failed: ${typeof error === "object" && error !== null && "message" in error ? String(error.message) : String(error)}`) } : {}
 			});
 			if (!isBuiltAdapter(built)) throw new Error(BAD_FACTORY_SHAPE_ERROR);
 		} catch (e) {
@@ -4191,6 +4498,10 @@ function createProviderPublisher(deps = {}) {
 * 它只回答「重建会不会改变什么」：目录顺序里的模型 id，每个带上 descriptor 用的
 * 同一个 vision 判定（id 没变但模态翻了也必须重建），加上允许清单。目录条目里其他
 * 东西变了不影响注册的 offer。
+*
+* **不含展示名 `name`**：模型展示名变化不影响注册的 offer（descriptor 里的 `name`
+* 只是显示用的），重新注册是浪费——期间在途请求可能被打断。展示名变化不改变
+* 模型的能力、窗口或输出上限，所以不参与签名。
 * @param {object[]} entries - 归一目录条目。
 * @param {string[]} enabledIds - 允许清单（空 = 全部）。
 * @returns {string}
@@ -4198,8 +4509,7 @@ function createProviderPublisher(deps = {}) {
 function catalogSignature(entries, enabledIds) {
 	return `${(Array.isArray(entries) ? entries : []).map((entry) => {
 		const e = entry;
-		const id = str(e?.id, "");
-		return `${id}:v${isVisionModel(e) ? 1 : 0}:n${str(e?.name, id)}:c${typeof e?.contextWindow === "number" ? e.contextWindow : ""}:o${typeof e?.maxOutputLength === "number" ? e.maxOutputLength : ""}`;
+		return `${str(e?.id, "")}:v${isVisionModel(e) ? 1 : 0}:c${typeof e?.contextWindow === "number" ? e.contextWindow : ""}:o${typeof e?.maxOutputLength === "number" ? e.maxOutputLength : ""}`;
 	}).join(",")}|${(Array.isArray(enabledIds) ? enabledIds : []).join(",")}`;
 }
 /**
@@ -4349,7 +4659,7 @@ function createProviderReconciler(deps) {
 			while (dirty) {
 				dirty = false;
 				await runOnce();
-				if (++guard > 100) break;
+				if (++guard > 20) break;
 			}
 		});
 	};
@@ -4372,6 +4682,7 @@ const TOKEN_FORGET_PATH = "/api/dsh-connect-modelscope-token-plan/token/forget";
 const PROBE_PATH = "/api/dsh-connect-modelscope-token-plan/probe";
 const PROVIDER_PATH = "/api/dsh-connect-modelscope-token-plan/provider";
 const DRAW_PATH = "/api/dsh-connect-modelscope-token-plan/draw";
+const TREND_WINDOW_PATH = "/api/dsh-connect-modelscope-token-plan/trend/window";
 
 //#endregion
 //#region src/host/snapshot-aggregate.ts
@@ -4417,12 +4728,14 @@ async function soft(promise) {
 }
 /** 聚合快照 body。wiring 子集见 routes/snapshot.ts 的 Pick。 */
 async function buildSnapshotBody(wiring) {
-	const { settings, tokenStore, usageStore, inference, providerStore, drawStore, publisher } = wiring;
+	const { settings, tokenStore, usageStore, inference, providerStore, drawStore, usagePrefsStore, publisher } = wiring;
+	const panelWindow = await usagePrefsStore.windowDays().catch(() => null);
+	const windowDays = resolveWindowDays(panelWindow, settings.trendDays, settings.retentionDays);
 	const [tokenState, daily, perModel, trend, events, providerNote] = await Promise.all([
 		soft(tokenStore.state()),
 		soft(usageStore.daily()),
 		soft(usageStore.perModelToday()),
-		soft(usageStore.trend(settings.trendDays)),
+		soft(usageStore.trend(windowDays)),
 		soft(usageStore.events()),
 		soft(providerStore.versionNote())
 	]);
@@ -4446,6 +4759,12 @@ async function buildSnapshotBody(wiring) {
 	if (providerNote.ok && providerNote.value !== null) shapeWarnings.push(providerNote.value);
 	const drawNote = await soft((async () => drawStore.versionNote())());
 	if (drawNote.ok && drawNote.value !== null) shapeWarnings.push(drawNote.value);
+	const windowNote = await soft((async () => usagePrefsStore.versionNote())());
+	if (windowNote.ok && windowNote.value !== null) shapeWarnings.push(windowNote.value);
+	if (curatedCatalogStale()) {
+		const age = curatedCatalogAgeDays();
+		shapeWarnings.push(`context-catalog: curated windows were last verified on ${CURATED_AS_OF}` + (age === null ? "" : ` (${age} days ago)`) + " — re-check them against the current catalogue");
+	}
 	const provider = await soft((async () => {
 		const panel = await providerStore.enabled().catch(() => null);
 		const enabled = resolveSwitchEnabled(panel, settings.registerProvider);
@@ -4473,14 +4792,19 @@ async function buildSnapshotBody(wiring) {
 	const draw = await soft((async () => {
 		const panel = await drawStore.enabled().catch(() => null);
 		const panelModel = await drawStore.modelId().catch(() => null);
-		const candidateIds = imageGenModelIds(modelEntries);
+		const candidates = drawCandidates(modelEntries);
+		const preferred = resolveSwitchValue(panelModel, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
+		const choice = resolveDrawModelChoice(modelEntries, void 0, preferred ?? void 0);
 		return {
 			enabled: resolveSwitchEnabled(panel, settings.drawEnabled),
 			source: switchSource(panel),
-			candidateIds,
-			candidateCount: candidateIds.length,
-			preferredModel: resolveSwitchValue(panelModel, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null,
+			candidateIds: candidates.map((row) => row.id),
+			candidateCount: candidates.length,
+			candidates,
+			preferredModel: preferred,
 			preferredSource: switchSource(panelModel),
+			effectiveModel: choice.id,
+			effectiveSource: choice.source,
 			absentReason: drawToolNote(),
 			mountPending: resolveSwitchEnabled(panel, settings.drawEnabled) === true && drawToolNote() !== null,
 			toolName: "modelscope_draw_image"
@@ -4527,7 +4851,9 @@ async function buildSnapshotBody(wiring) {
 		},
 		events: events.ok ? events.value : [],
 		trend: {
-			days: settings.trendDays,
+			days: windowDays,
+			windowDays: panelWindow,
+			maxDays: settings.retentionDays,
 			buckets: trend.ok ? trend.value : []
 		},
 		models: {
@@ -4585,7 +4911,7 @@ async function readJsonBody(request, limit = MAX_JSON_BODY_BYTES) {
 			received += buffer.byteLength;
 			if (received > limit) return {
 				ok: false,
-				error: "request body is too large"
+				error: `request body is too large (max ${limit} bytes)`
 			};
 			chunks.push(buffer);
 		}
@@ -4941,22 +5267,22 @@ function registerProbeRoute(ctx, wiring) {
 * @module dsh-connect-modelscope-token-plan/routes/provider
 */
 /**
-* 读目录条目，读不到按空目录降级（GET 不能因目录失败把整个面板状态打掉）。
+* 读目录条目，读不到**抛错**（让 snapshot() 走 respondError 返回 ok:false）。
 *
 * 读目录前先取**当前窗口覆盖**传给 `fetchModels`：条目在归一前打上覆盖标记，
 * descriptor / roster / catalogSignature 都从这份条目派生。每个写路由（开关、
 * 清单、窗口、reset）都经这里取条目再 publish，所以任何一次重注册都带着最新
 * 覆盖——否则先存窗口、再存清单会把未打标的目录重新注册上去，覆盖静默失效到
 * 下一轮轮询。
+*
+* **为什么抛错而不是降级成空目录**：空 roster 与「真的没有模型」在面板上长得
+* 一模一样（modelCount=0），而真相是「目录拉不到」——这与 snapshot-aggregate
+* 的 `models.available=false` 语义矛盾（后者明确区分「0 个模型」与「读不到」）。
+* 抛错让 GET 返回 ok:false + error，面板能显示「目录拉不到」而不是「0 个模型」。
 */
 async function readEntries$1(inference, providerStore) {
 	const contextWindow = await optional(providerStore?.contextWindow?.(), null);
-	const catalog = await inference.fetchModels(contextWindow).catch((error) => {
-		return {
-			entries: [],
-			__error: error
-		};
-	});
+	const catalog = await inference.fetchModels(contextWindow);
 	return Array.isArray(catalog?.entries) ? catalog.entries : [];
 }
 /**
@@ -4987,14 +5313,27 @@ function registerProviderRoute(ctx, wiring) {
 	/**
 	* 组装一份 §9 响应形状。GET 与成功后的 POST 共用，所以两个方向不可能对「当前
 	* 状态是什么」说两套话。
+	*
+	* **目录读不到怎么办**：GET 是权威读路径，读不到就让它失败（handler 转
+	* `respondError`，面板看见「目录拉不到」而不是「0 个模型」）。POST 的响应只是
+	* 保存后的回读，而此时**保存已经成功**——不能把一次成功的写报成失败，所以
+	* `tolerateCatalogFailure` 让它降级为空 roster 并带上 `catalogError` 说明原因。
 	* @param {object} [extra] - 调用方要追加/覆盖的字段。
+	* @param {object} [options] - `{ tolerateCatalogFailure }`：写成功后的回读宽容模式。
 	* @returns {Promise<object>} 响应体。
 	*/
-	const snapshot = async (extra = {}) => {
+	const snapshot = async (extra = {}, options = {}) => {
 		const panelSwitch = await optional(providerStore.enabled());
 		const enabledIds = await readEnabledIds(providerStore, publisher.state.enabledIds);
 		const contextWindow = await optional(providerStore.contextWindow?.(), null);
-		const entries = await readEntries$1(inference, providerStore);
+		let entries = [];
+		let catalogError = null;
+		try {
+			entries = await readEntries$1(inference, providerStore);
+		} catch (error) {
+			if (options.tolerateCatalogFailure !== true) throw error;
+			catalogError = redactedError(error);
+		}
 		const roster = rosterWithAvailability(entries, []);
 		const allowedList = parseAllowedList(enabledIds);
 		const modelCount = roster.length;
@@ -5011,6 +5350,7 @@ function registerProviderRoute(ctx, wiring) {
 			enabledIds,
 			contextWindow,
 			roster,
+			...catalogError !== null ? { catalogError } : {},
 			...extra
 		};
 	};
@@ -5021,7 +5361,11 @@ function registerProviderRoute(ctx, wiring) {
 		handler: withOrigin(async (request, response) => {
 			const method = request.method === void 0 ? "GET" : request.method;
 			if (method === "GET") {
-				writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+				try {
+					writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+				} catch (error) {
+					respondError(response, error);
+				}
 				return;
 			}
 			if (method !== "POST") {
@@ -5044,7 +5388,7 @@ function registerProviderRoute(ctx, wiring) {
 				respondError(response, error);
 				return;
 			}
-			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+			writeJson(response, 200, await snapshot({}, { tolerateCatalogFailure: true }), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
 	offs.push(ctx.webServer.register({
@@ -5072,7 +5416,7 @@ function registerProviderRoute(ctx, wiring) {
 				respondError(response, error);
 				return;
 			}
-			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+			writeJson(response, 200, await snapshot({}, { tolerateCatalogFailure: true }), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
 	offs.push(ctx.webServer.register({
@@ -5099,7 +5443,7 @@ function registerProviderRoute(ctx, wiring) {
 				respondError(response, error);
 				return;
 			}
-			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+			writeJson(response, 200, await snapshot({}, { tolerateCatalogFailure: true }), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
 	offs.push(ctx.webServer.register({
@@ -5122,7 +5466,7 @@ function registerProviderRoute(ctx, wiring) {
 				respondError(response, error);
 				return;
 			}
-			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+			writeJson(response, 200, await snapshot({}, { tolerateCatalogFailure: true }), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
 	return () => {
@@ -5186,16 +5530,20 @@ function registerDrawRoute(ctx, wiring) {
 		const panelSwitch = await optional(drawStore.enabled());
 		const panelModelId = await optional(drawStore.modelId());
 		const entries = await readEntries(inference);
-		const candidateIds = imageGenModelIds(entries);
-		const effectiveModelId = resolveSwitchValue(panelModelId, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
+		const candidates = drawCandidates(entries);
+		const preferredModelId = resolveSwitchValue(panelModelId, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
+		const choice = resolveDrawModelChoice(entries, void 0, preferredModelId ?? void 0);
 		return {
 			ok: true,
 			enabled: resolveSwitchEnabled(panelSwitch, settings.drawEnabled),
 			source: switchSource(panelSwitch),
-			candidateIds,
-			candidateCount: candidateIds.length,
-			preferredModel: effectiveModelId,
+			candidateIds: candidates.map((row) => row.id),
+			candidateCount: candidates.length,
+			candidates,
+			preferredModel: preferredModelId,
 			preferredSource: switchSource(panelModelId),
+			effectiveModel: choice.id,
+			effectiveSource: choice.source,
 			absentReason: drawToolNote(),
 			/**
 			* 开关的保存**不会**改变本次挂载的工具。
@@ -5288,6 +5636,95 @@ function registerDrawRoute(ctx, wiring) {
 	};
 }
 
+//#endregion
+//#region src/host/routes/usage-prefs.ts
+/**
+* 趋势图**显示窗口**路由：读当前窗口（GET）与保存（POST）。
+*
+* 一条路径两件事：
+*   - GET  `TREND_WINDOW_PATH`   读面板覆盖 + 生效天数 + 上界（无副作用）；
+*   - POST `TREND_WINDOW_PATH`   body `{ windowDays: number|null }` → 保存
+*     （`null` = 清除覆盖，回到 `trendDays` 配置默认）。
+*
+* **与 provider / draw 路由不同，本路由保存后不触发任何收敛**：显示窗口只影响
+* 快照里 `trend` 那一段，面板保存成功后自己调一次 `load()` 就当场回显；没有
+* 需要重建的注册态。
+*
+* 越界值**夹取而不是拒绝**：上界是保留窗口（`settings.retentionDays`），而
+* host-config 对配置里的同一个值也是夹——两处若一个夹一个拒，同一个越界值会因
+* 来源不同得到两个下场。类型给错（字符串 / 缺字段）仍然按 400 拒：那是形状错，
+* 不是范围错。
+*
+* peer-free：不 import 任何 Host peer。
+* @module dsh-connect-modelscope-token-plan/routes/usage-prefs
+*/
+/**
+* 注册趋势窗口路由。
+* @param ctx - host 根上下文（只用 `ctx.webServer`）。
+* @param {UsagePrefsRouteWiring} wiring - 本路由读到的子集。
+* @returns {Function} 注销回调。
+*/
+function registerUsagePrefsRoute(ctx, wiring) {
+	const { settings, usagePrefsStore, logger } = wiring;
+	/**
+	* 组装响应。GET 与写成功后的响应共用，两个方向不可能对「当前窗口」说两套话。
+	* @param {object} [extra] - 追加/覆盖字段。
+	* @returns {Promise<object>} 响应体。
+	*/
+	const snapshot = async (extra = {}) => {
+		const panel = await optional(usagePrefsStore.windowDays());
+		return {
+			ok: true,
+			windowDays: panel,
+			days: resolveWindowDays(panel, settings.trendDays, settings.retentionDays),
+			maxDays: settings.retentionDays,
+			source: switchSource(panel),
+			...extra
+		};
+	};
+	const off = ctx.webServer.register({
+		kind: "exact",
+		path: TREND_WINDOW_PATH,
+		handler: withOrigin(async (request, response) => {
+			const method = request.method === void 0 ? "GET" : request.method;
+			if (method === "GET") {
+				writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+				return;
+			}
+			if (method !== "POST") {
+				refuseMethod(response);
+				return;
+			}
+			const body = await readJsonBodyOr400(request, response);
+			if (body === null) return;
+			const isNull = body.windowDays === null;
+			const isNumber = typeof body.windowDays === "number" && Number.isFinite(body.windowDays);
+			if (!isNull && !isNumber) {
+				writeJson(response, 400, {
+					ok: false,
+					error: "expected { windowDays: number | null }"
+				}, { "cache-control": "no-store" });
+				return;
+			}
+			const saved = isNull ? null : Math.min(Math.max(1, Math.floor(body.windowDays)), settings.retentionDays);
+			try {
+				await usagePrefsStore.saveWindowDays(saved);
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	});
+	return () => {
+		try {
+			off();
+		} catch (error) {
+			logger?.warn?.(`trend window route unregister failed: ${redactedError(error)}`);
+		}
+	};
+}
+
 //#endregion
 //#region src/host/routes.ts
 /**
@@ -5304,7 +5741,8 @@ function registerRoutes(ctx, wiring) {
 		...registerTokenRoute(ctx, wiring),
 		registerProbeRoute(ctx, wiring),
 		registerProviderRoute(ctx, wiring),
-		registerDrawRoute(ctx, wiring)
+		registerDrawRoute(ctx, wiring),
+		registerUsagePrefsRoute(ctx, wiring)
 	];
 }
 
@@ -5352,7 +5790,7 @@ function apply(ctx, config = {}, deps = {}) {
 	const usageStore = createFileUsageStore({
 		name,
 		profile,
-		trendDays: settings.trendDays,
+		retentionDays: settings.retentionDays,
 		maxEvents: settings.maxEvents,
 		logger: ctx.logger
 	});
@@ -5370,6 +5808,10 @@ function apply(ctx, config = {}, deps = {}) {
 		profile,
 		logger: ctx.logger
 	});
+	const usagePrefsStore = createFileUsagePrefsStore({
+		profile,
+		logger: ctx.logger
+	});
 	const publisher = createProviderPublisher({
 		settings,
 		panelSwitch: () => providerStore.enabled(),
@@ -5401,6 +5843,7 @@ function apply(ctx, config = {}, deps = {}) {
 		inference,
 		providerStore,
 		drawStore,
+		usagePrefsStore,
 		publisher,
 		reconcile,
 		logger: ctx.logger