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

package/lib/index.js

@@ -1,5 +1,5 @@
-import { C as optional, D as verbatim, E as str, S as obj, T as redactSecrets$1, _ as hasHardQuotaWordingIn, a as resolveSettings, b as degrade, c as LLM_PROVIDER_ID, d as isVisionModel, f as normalizeEntry, h as textToImageModelIds, i as name, m as rosterWithAvailability, n as inject, p as resolveAllowedList, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as imageGenModelIds, v as looksLikeRateLimit, w as pluginError, x as errMsg } from "./host-config.js";
-import { join } from "node:path";
+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";
 import { homedir } from "node:os";
@@ -90,6 +90,44 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 	const resolveService = () => {
 		return (typeof credentials === "function" ? credentials() : credentials) ?? null;
 	};
+	/**
+	* 解析当前令牌与来源（实现体）。
+	*
+	* 提成局部函数而不是只做返回对象上的方法：`state()` 也要走同一条路，而方法里
+	* 调 `this.resolve()` 是一个**解构即崩**的 footgun——`const { state } =
+	* createTokenStore(...)` 之后 `this` 是 undefined，调用直接 TypeError。当前
+	* 调用点都规规矩矩用方法调用所以没炸，但那是运气，不是设计。返回类型显式
+	* 注解：这是快照 TokenStatus.source 联合类型的上游，靠推断会把字面量联合
+	* 拓宽成 string。
+	* @returns {Promise<{value: string, source: ("credentials"|"memory"|"env"|null)}>}
+	*/
+	const resolveToken = async () => {
+		try {
+			const service = resolveService();
+			if (service !== null && typeof service.resolve === "function") {
+				const resolved = await service.resolve(TOKEN_REF).catch(() => void 0);
+				const value = verbatim(resolved?.value, "");
+				if (typeof value === "string" && value.trim() !== "") return {
+					value,
+					source: "credentials"
+				};
+			}
+		} catch {}
+		const held = memory.get(TOKEN_REF);
+		if (typeof held === "string" && held.trim() !== "") return {
+			value: held,
+			source: "memory"
+		};
+		const fromEnv = verbatim(env[TOKEN_REF], "");
+		if (typeof fromEnv === "string" && fromEnv.trim() !== "") return {
+			value: fromEnv,
+			source: "env"
+		};
+		return {
+			value: "",
+			source: null
+		};
+	};
 	return {
 		/**
 		* 把面板输入的令牌存成引用；原样存（不 trim），空白值视为没输入。
@@ -107,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);
@@ -122,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 路由是唯一调用方）。
@@ -146,36 +189,11 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 			};
 		},
 		/**
-		* 解析当前令牌与来源。返回类型显式注解：这是快照 TokenStatus.source
-		* 联合类型的上游，靠推断会把字面量联合拓宽成 string。
+		* 解析当前令牌与来源。
 		* @returns {Promise<{value: string, source: ("credentials"|"memory"|"env"|null)}>}
 		*/
 		async resolve() {
-			try {
-				const service = resolveService();
-				if (service !== null && typeof service.resolve === "function") {
-					const resolved = await service.resolve(TOKEN_REF).catch(() => void 0);
-					const value = verbatim(resolved?.value, "");
-					if (typeof value === "string" && value.trim() !== "") return {
-						value,
-						source: "credentials"
-					};
-				}
-			} catch {}
-			const held = memory.get(TOKEN_REF);
-			if (typeof held === "string" && held.trim() !== "") return {
-				value: held,
-				source: "memory"
-			};
-			const fromEnv = verbatim(env[TOKEN_REF], "");
-			if (typeof fromEnv === "string" && fromEnv.trim() !== "") return {
-				value: fromEnv,
-				source: "env"
-			};
-			return {
-				value: "",
-				source: null
-			};
+			return resolveToken();
 		},
 		/**
 		* 无秘密的状态描述（快照与面板消费）。
@@ -192,7 +210,7 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		* `memory` 才真的只在本次进程存活期间存在。
 		*/
 		async state() {
-			const { source } = await this.resolve();
+			const { source } = await resolveToken();
 			return {
 				present: source !== null,
 				source: source === null ? "none" : source,
@@ -207,9 +225,11 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 //#endregion
 //#region src/host/state-store.ts
 /**
-* 状态文件公共原语。**TL;DR**：本文件只做三件事——`dshHome`/`stateDir`（定位
-* 状态目录）、`profileSegment`（按 profile 分段路径）、以及 {@link createStateReadCache}
-* （统一读缓存）。其余一切遵守下方「行为约定」。
+* 状态文件公共原语。**TL;DR**：本文件只做四件事——`dshHome`/`stateDir`（定位
+* 状态目录）、`profileSegment`（按 profile 分段路径）、{@link createStateReadCache}
+* （统一读缓存）、以及写侧三件套（{@link createStateWriteQueue} 写串行化 /
+* {@link guardStateWrite} ADR-006 写守卫 / {@link stateVersionNote} 读侧版本说明）。
+* 其余一切遵守下方「行为约定」。
 *
 * 把本插件各 store（usage-store / provider / draw）各自手写的同一段
 * "版本载荷 + temp 文件 + rename 原子 + 0600 + 损坏即忽略" 收敛到这里。
@@ -234,6 +254,13 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 * 2. 第二步收敛的是**读缓存**：provider / draw 早有 1s TTL，而 catalog 完全
 *    没有（进程内永不失效）——同一个「两个进程共享一个 state 目录」的问题修了
 *    两个、漏了第三个。现在统一走 {@link createStateReadCache}，一个 TTL 三个调用方。
+* 3. 第三步收敛的是**写侧三件套**。这三个 store 曾各自手写：provider 有
+*    writeChain、usage 有 writeChain、draw **两个都没有**（并发保存丢一次、
+*    磁盘 version 比本构建新时降级覆写、读侧静默读作「没设过」——2026-10-17
+*    实测复现，正是 provider-store 注释里记着「咬过三次」的那类漂移的第四条）。
+*    现在三件套各有一份公共实现：串行化是{@link createStateWriteQueue}、写守卫是
+*    {@link guardStateWrite}、读侧说明是{@link stateVersionNote}；provider /
+*    usage / draw 三个 store 都是调用方，不再各写一遍。
 *
 * @module dsh-connect-modelscope-token-plan/state-store
 */
@@ -605,11 +632,113 @@ async function readStateVersion(file) {
 function isKnownStateVersion(version, known) {
 	return version === null || known.includes(version);
 }
+/**
+* 写串行化队列——store 的「读-改-写必须排队」的那把链。
+*
+* 为什么这不是某个 store 的私事：三个 store（provider / usage / draw）各写过
+* 一份一模一样的 `let writeChain = Promise.resolve(...)`，而 draw 曾经**两份都
+* 没有**——并发 `saveEnabled(true)` + `saveModelId(...)` 各自读到同一个 current，
+* 后写的赢，前一次保存被整个丢掉（2026-10-17 实测：落盘只剩其中一个字段）。
+* provider-store 的注释记着这类漂移「咬过三次」，draw 是第四条。抽到这里，
+* 第四个 store 起只需调用，没有「再手写一遍」这个选项。
+*
+* 语义（与 provider / usage 此前的私有实现逐字一致）：
+*   - `task` 在上一个任务落幕后才起动，临界区内重新读盘（基线不来自 TTL 缓存）；
+*   - **调用方拿到的是 `run` 本身**——拒绝照旧传播（provider 的 `save()` 要抛给
+*     路由、usage 的 `recordCall()` 也要抛），因为吞掉失败是调用方的语义决定；
+*   - 链自己吞掉失败继续走：一次只读 Home 上的写失败不该毒化后续所有保存。
+*
+* peer-free，与其余原语同纪律。
+* @returns {{
+*   enqueue: <T>(task: () => Promise<T>) => Promise<T>
+* }} 排队执行一次任务。
+*/
+function createStateWriteQueue() {
+	let chain = Promise.resolve();
+	return { enqueue(task) {
+		const run = chain.then(task);
+		chain = run.then(() => void 0, () => void 0);
+		return run;
+	} };
+}
+/**
+* ADR-006 写侧守卫：本构建读不懂的版本，不许覆盖。
+*
+* 磁盘上出现一个**本构建不认识的数字版本**，只可能是更新的构建写的；用一个旧
+* 载荷盖掉它，销毁的是我们根本看不见的数据（实测过一次 version 2 → 1 的降级
+* 覆写，110 次历史归零）。所以写入前先问盘，三种答案：
+*   - `null`（没有文件 / 没有版本 / 损坏）——没有什么可保护，写是恢复手段，放行；
+*   - 已知版本——放行；
+*   - 未知数字版本，或文件**在场却读不出来**（EACCES/EBUSY/EIO）——拒写。
+*     后者由 {@link readStateVersion} 抛出来（它只把 ENOENT 读作「没有文件」），
+*     这里接住并拒写：「读不到」不等于「没有东西要保护」。
+*
+* 拒写返回一句**已 degrade 记录**的原因（调用方决定要不要再抛给用户——provider
+* 的 save 抛、draw 的 saveEnabled 抛、usage 的 recordCall 静默 no-op），而不是
+* 静默 no-op： swallow the failure, not the reason。
+*
+* @param {string} file - 目标状态文件路径（消息里只取 basename）。
+* @param {readonly number[]} known - 本构建读得懂的版本集合。
+* @param {{label: string, logger?: {warn?: (m: string) => void}|undefined}} options -
+*   `label` 进拒绝消息的前缀（如 `"provider"` / `"draw-state"`）。`logger` 的
+*   `| undefined` 不是冗余：tsconfig 开了 `exactOptionalPropertyTypes`，而各 store
+*   解构出来的 `logger` 本身就带着 `undefined`（属性可选），不写这一半编译不过。
+* @returns {Promise<string|null>} 拒绝原因（已记日志），放行时为 `null`。
+*/
+async function guardStateWrite(file, known, options) {
+	const base = basename(file);
+	let existing;
+	try {
+		existing = await readStateVersion(file);
+	} catch (error) {
+		const reason = `${options.label}: refusing to overwrite ${base} (cannot read it: ${redactSecrets(errMsg(error))})`;
+		degrade(reason, null, options.logger, null);
+		return reason;
+	}
+	if (!isKnownStateVersion(existing, known)) {
+		const reason = `${options.label}: refusing to overwrite ${base} holding version ${existing} (this build knows ${known.join("/")})`;
+		degrade(reason, null, options.logger, null);
+		return reason;
+	}
+	return null;
+}
+/**
+* 读侧版本说明：磁盘上那份文件带着本构建读不懂的版本时，给操作者的一句话。
+*
+* 为什么读侧宽容还要说话：写侧守卫挡住了覆盖，读侧按设计把未知版本**宽容地**
+* 读作「没设过」——于是「保存的值被忽略」在面板上呈现成「从未保存过」。对
+* provider 的允许清单，这两者读出的方向是危险的（空清单 = 不过滤 = 提供全部
+* 模型）；对 draw 的开关，回退方向是 patch 默认（通常 = 关）。闸与说明是同一条
+* 承诺的两半，缺了哪半都静默。
+*
+* `consequence` 由调用方给：每个 store 知道自己「读作没设过」意味着什么，公共
+* 原语只负责把文件名、版本号、已知版本集合与下一步动作说全。
+*
+* @param {object} options
+* @param {string} options.label - 消息前缀（如 `"provider-state"`）。
+* @param {string} options.file - 状态文件路径（消息里只取 basename）。
+* @param {number} options.version - 盘上的版本号（调用方已判过是未知的）。
+* @param {readonly number[]} options.known - 本构建读得懂的版本集合。
+* @param {string} options.consequence - 「读作没设过」对这个 store 意味着什么。
+* @returns {string} 人读的一句警告。
+*/
+function stateVersionNote(options) {
+	return `${options.label}: ${basename(options.file)} holds version ${options.version}, which this build cannot read (this build knows ${options.known.join("/")}); ${options.consequence} Upgrade this build to see the saved values, or delete the file to reset them.`;
+}
 
 //#endregion
-//#region src/host/codes.ts
+//#region src/shared/codes.ts
 /**
-* 错误分类的单一真源（对齐姊妹插件的 codes.ts 纪律）。
+* 错误分类码表的**单一真源**——Host 与 Client 同读这一份。
+*
+* 为什么从 `host/codes.ts` 搬来：这张表曾经在 Client 侧有一份「刻意副本」
+* （`client/snapshot.ts` 的 `CLIENT_CODE`），理由是「浏览器无法 import Host
+* 模块」。那个理由已经过期——`shared/wire.ts` 的运行时值（如
+* `SNAPSHOT_REQUIRED_KEYS`）早就在双端 import，浏览器 bundle 拿得到 shared/
+* 下的任何模块。两份表必然漂移，而漂移的后果是最需要人看的内部错误没有引导
+* 文案（INTERNAL_ERROR 当初就是这么漏的）。码表住 shared，Host 的分类函数
+* （`classifyStatus` / `classifyRateLimit` / `parseRetryAfterMs`）留在
+* `host/codes.ts`——那些读上游响应，是 Host 独有的行为。
 *
 * 魔搭的分类现实（SPIKE.md）：上游不带任何额度头，额度耗尽与每分钟限频都只
 * 会以 429 + 文案出现，所以 429 的分诊是**按 body 文案**做的保守二分——
@@ -619,8 +748,8 @@ function isKnownStateVersion(version, known) {
 * @module dsh-connect-modelscope-token-plan/codes
 */
 /**
-* 面板按它分流的稳定码表 —— Client 的 `GUIDANCE_BY_CODE` 以这份表的键为契约，
-* 新增/改名必须同步 Client，否则内部错误没有引导文案（见下 `INTERNAL_ERROR`）。
+* 面板按它分流的稳定码表 —— Client 的 `GUIDANCE_BY_CODE` 以这份表的键为契约
+* （且以 `CodeValue` 为**类型**契约：缺键是编译错误，不再只靠测试红）。
 */
 const CODE = Object.freeze({
 	CONFIG_ERROR: "config_error",
@@ -643,12 +772,26 @@ const CODE = Object.freeze({
 	* Client 自产码：Host 响应无法解读成快照（非 JSON / 缺 ok 字段）时，
 	* 面板用它走引导文案，而不是把裸英文串（"unexpected payload"）上屏。
 	*
-	* 本表是 `GUIDANCE_BY_CODE` 的键集真源（panel.test §2 钉「每个键必须在
-	* CODE 里」、§3c 钉「每个码必须有引导」）——新增 client 码必须同时进
+	* 本表是 `GUIDANCE_BY_CODE` 的键集真源——新增 client 码必须同时进
 	* 这张表，两侧才同步。
 	*/
 	PAYLOAD_ERROR: "payload_error"
 });
+
+//#endregion
+//#region src/host/codes.ts
+/**
+* Host 侧的 429 分诊分类函数。**码表本身已迁至 `shared/codes.ts`**（双端同读，
+* 见那里的搬迁理由）；本文件只剩「读上游响应」的 Host 独有行为，并把 CODE
+* 再导出一次，让 Host 各模块的 `from "./codes.ts"` 导入路径不变。
+*
+* 魔搭的分类现实（SPIKE.md）：上游不带任何额度头，额度耗尽与每分钟限频都只
+* 会以 429 + 文案出现，所以 429 的分诊是**按 body 文案**做的保守二分——
+* QUOTA_EXCEEDED 快速失败不重试，RATE_LIMITED 交给调用方退避。分不清时归
+* RATE_LIMITED（退避是两方向里更安全的那个）。
+*
+* @module dsh-connect-modelscope-token-plan/codes
+*/
 /**
 * 把上游 HTTP 状态归类成稳定码。
 *
@@ -690,11 +833,7 @@ function classifyStatus(status) {
 function classifyRateLimit(message) {
 	if (typeof message !== "string" || message.length === 0) return "rate_limit";
 	if (looksLikeRateLimit(message)) return "rate_limit";
-	return hasHardQuotaWording(message) ? "quota" : "rate_limit";
-}
-/** 文本是否含硬额度措辞（真耗尽，不纠正）——直接问 llm-error-fix 的那张表。 */
-function hasHardQuotaWording(message) {
-	return hasHardQuotaWordingIn(message);
+	return hasHardQuotaWordingIn(message) ? "quota" : "rate_limit";
 }
 /**
 * 解析 Retry-After（秒或 HTTP 日期）与平台文案里写明的等待时长。
@@ -838,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。 */
@@ -859,8 +999,10 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 		events: []
 	};
 	let loaded = false;
-	/** 写串行化：读-改-写必须排队，两个并发 recordCall 不能互相覆盖。 */
-	let writeChain = Promise.resolve();
+	/** 写串行化：读-改-写必须排队，两个并发 recordCall 不能互相覆盖。
+	队列实现在 state-store（{@link createStateWriteQueue}）——provider / draw
+	同款，三份私有副本正是 draw-store 曾经三件全缺的入口。 */
+	const writeQueue = createStateWriteQueue();
 	/**
 	* 磁盘版本闸 —— 读路径与写路径**各自**调用，不共享副作用。
 	*
@@ -880,7 +1022,7 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 		try {
 			onDisk = await readStateVersion(file);
 		} catch (error) {
-			const note = `usage-state: usage.json exists but cannot be read (${redactSecrets$1(errMsg(error))})`;
+			const note = `usage-state: usage.json exists but cannot be read (${redactSecrets(errMsg(error))})`;
 			if (!readOnly) logger?.warn?.(`${name}: ${note} — recording disabled to avoid clobbering`);
 			anomaly = note;
 			readOnly = true;
@@ -915,26 +1057,22 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 		cache.remember(payload);
 	};
 	/** 排队执行一次读-改-写；只读闸置位时整个变更是 no-op。 */
-	const enqueue = (mutate) => {
-		const run = writeChain.then(async () => {
-			if (await diskVersionBlocksWrites()) return;
-			const payload = await readThrough() ?? (loaded ? current : null) ?? {
-				version: STATE_VERSION,
-				days: {},
-				models: {},
-				events: []
-			};
-			mutate(payload);
-			current = payload;
-			loaded = true;
-			await persist(payload);
-		});
-		writeChain = run.catch(() => {});
-		return run;
-	};
-	/** 修剪：只留最近 trendDays 个天桶（按 dateKey 排序，今天不删）。 */
+	const enqueue = (mutate) => writeQueue.enqueue(async () => {
+		if (await diskVersionBlocksWrites()) return;
+		const payload = await readThrough() ?? (loaded ? current : null) ?? {
+			version: STATE_VERSION,
+			days: {},
+			models: {},
+			events: []
+		};
+		mutate(payload);
+		current = payload;
+		loaded = true;
+		await persist(payload);
+	});
+	/** 修剪：只留最近 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];
 	};
@@ -1047,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();
@@ -1275,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,
@@ -1361,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();
@@ -1372,7 +1562,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 			});
 		} catch (error) {
 			if (error instanceof Error && error.name === "AbortError") throw pluginError(CODE.TIMEOUT_ERROR, "modelscope request timed out");
-			throw pluginError(CODE.NETWORK_ERROR, redactSecrets$1(errMsg(error)));
+			throw pluginError(CODE.NETWORK_ERROR, redactSecrets(errMsg(error)));
 		} finally {
 			clearTimeout(timer);
 		}
@@ -1380,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 {
@@ -1407,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);
@@ -1418,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));
+		}
+		let json;
+		try {
+			json = await response.json();
+		} catch {
+			discardBody(response);
+			throw new Error("model detail body was not JSON");
 		}
-		const json = await response.json().catch(() => null);
-		if (json === null || typeof json !== "object" || json.Code !== 200) return [];
+		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 : []) {
@@ -1462,18 +1665,27 @@ 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);
 					const code = classifyStatus(response.status);
-					throw pluginError(code, redactSecrets$1("model catalog failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
+					throw pluginError(code, redactSecrets("model catalog failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
 				}
 				const json = await response.json().catch(() => null);
 				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) => {
@@ -1513,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
@@ -1536,7 +1748,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 				if (!response.ok) {
 					const message = await readErrorMessage(response);
 					const code = classifyStatus(response.status);
-					throw pluginError(code, redactSecrets$1("magicube balance failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
+					throw pluginError(code, redactSecrets("magicube balance failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
 				}
 				const json = await response.json().catch(() => null);
 				const data = json !== null && typeof json === "object" ? json.data : null;
@@ -1578,14 +1790,14 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 			const elapsedMs = Date.now() - startedAt;
 			if (response.status === 401 || response.status === 403) {
 				const message = await readErrorMessage(response);
-				throw pluginError(CODE.AUTH_ERROR, redactSecrets$1(message === "" ? "token rejected (HTTP 401/403)" : message));
+				throw pluginError(CODE.AUTH_ERROR, redactSecrets(message === "" ? "token rejected (HTTP 401/403)" : message));
 			}
 			if (response.status === 429) {
 				const message = await readErrorMessage(response);
 				const retryAfterMs = parseRetryAfterMs(response.headers, message);
 				const triage = classifyRateLimit(message);
 				const extra = retryAfterMs !== null && retryAfterMs !== void 0 ? { retryAfterMs } : {};
-				throw pluginError(triage === "quota" ? CODE.QUOTA_EXCEEDED : CODE.RATE_LIMITED, redactSecrets$1(message === "" ? "modelscope returned 429 (probe on " + modelId + ")" : message), extra);
+				throw pluginError(triage === "quota" ? CODE.QUOTA_EXCEEDED : CODE.RATE_LIMITED, redactSecrets(message === "" ? "modelscope returned 429 (probe on " + modelId + ")" : message), extra);
 			}
 			if (response.status >= 500) throw pluginError(CODE.UPSTREAM_ERROR, "modelscope returned HTTP " + String(response.status) + " (validity probe)");
 			response.body?.cancel();
@@ -1648,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,
@@ -1795,28 +2007,22 @@ function createFileProviderStore(options = {}) {
 	* read. An unknown NUMERIC version means a NEWER build wrote it; clobbering
 	* it destroys data we cannot even see. So the write is refused with a
 	* `degrade` signal, not a silent no-op — swallow the failure, not the reason.
+	* The guard itself lives in `state-store.ts` ({@link guardStateWrite}) — it is
+	* the same promise draw-store makes, and two copies of "what may be
+	* overwritten" is one copy too many.
 	* @param {object} body - the JSON body to persist.
 	* @returns {Promise<string|null>} the refusal reason when the write was
 	*   refused (already `degrade`-logged), or `null` when it landed — the caller
 	*   decides whether to surface the refusal to a user.
 	*/
 	const writePayload = async (body) => {
-		let existing;
-		try {
-			existing = await readStateVersion(filePath);
-		} catch (error) {
-			const reason = `provider: refusing to overwrite provider.json (cannot read it: ${redactSecrets$1(errMsg(error))})`;
-			degrade(reason, null, logger, null);
-			return reason;
-		}
-		if (!isKnownStateVersion(existing, KNOWN_PROVIDER_VERSIONS)) {
-			const reason = `provider: refusing to overwrite provider.json holding version ${existing} (this build knows ${KNOWN_PROVIDER_VERSIONS.join("/")})`;
-			degrade(reason, null, logger, null);
-			return reason;
-		}
-		const temporary = temporaryOf(stateDir$1, "provider.json");
+		const refusal = await guardStateWrite(filePath, KNOWN_PROVIDER_VERSIONS, {
+			label: "provider",
+			logger
+		});
+		if (refusal !== null) return refusal;
 		await ensureStateDir(stateDir$1);
-		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary });
+		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir$1, "provider.json") });
 		return null;
 	};
 	const legacyFile = dir === void 0 && profile ? join(stateDir(name), "provider.json") : null;
@@ -1859,7 +2065,7 @@ function createFileProviderStore(options = {}) {
 	const parsePayload = async () => parseAt(filePath);
 	/** Read one payload off an explicit path (the legacy shared file). */
 	const parsePayloadFrom = async (file) => parseAt(file);
-	let writeChain = Promise.resolve(null);
+	const writeQueue = createStateWriteQueue();
 	const cache = createStateReadCache(async () => {
 		const own = await parsePayload();
 		if (own.enabled !== null || own.enabledIds !== null || legacyFile === null) return own;
@@ -1872,7 +2078,7 @@ function createFileProviderStore(options = {}) {
 			...legacy.enabledIds === null ? {} : { enabledIds: legacy.enabledIds },
 			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 		};
-		await writeChain.then(() => writePayload(inherited).then(() => void 0, () => void 0), () => writePayload(inherited).then(() => void 0, () => void 0));
+		await writeQueue.enqueue(() => writePayload(inherited).then(() => void 0, () => void 0));
 		return legacy;
 	}, { ttlMs });
 	const read = () => cache.read();
@@ -1883,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.
@@ -1918,7 +2124,7 @@ function createFileProviderStore(options = {}) {
 	* @returns {Promise<string|null>} the write refusal reason, or `null`.
 	*/
 	const patchPayload = (patch) => {
-		const run = writeChain.then(async () => {
+		return writeQueue.enqueue(async () => {
 			const current = await parsePayload();
 			/** `undefined` keeps the stored key; `null` clears it (key absent). */
 			const body = { version: 1 };
@@ -1938,8 +2144,6 @@ function createFileProviderStore(options = {}) {
 			});
 			return refusal;
 		});
-		writeChain = run.catch(() => null);
-		return run;
 	};
 	return {
 		/**
@@ -1994,7 +2198,13 @@ function createFileProviderStore(options = {}) {
 		async versionNote() {
 			const version = (await readPayload()).version;
 			if (version === null || isKnownProviderVersion(version)) return null;
-			return `provider-state: provider.json holds version ${version}, which this build cannot read (this build knows ${KNOWN_PROVIDER_VERSIONS.join("/")}); the saved switch and allow-list are being answered as "not set", so the allow-list reads as "no filter, offer every model" while the switch falls back to the config default. Upgrade this build to see the saved values, or delete the file to reset them.`;
+			return stateVersionNote({
+				label: "provider-state",
+				file: filePath,
+				version,
+				known: KNOWN_PROVIDER_VERSIONS,
+				consequence: "the saved switch and allow-list are being answered as \"not set\", so the allow-list reads as \"no filter, offer every model\" while the switch falls back to the config default."
+			});
 		},
 		/**
 		* Persist a switch value. The write is atomic (temp file + rename) so a
@@ -2069,8 +2279,27 @@ function createFileProviderStore(options = {}) {
 * 优先级与所有 opt-in 开关同一份裁决（`switch-precedence.ts`）：面板保存值赢，
 * 否则 `cordis.patch.yml` 的 `drawEnabled` 默认值说了算。
 *
-* 完整性沿用 `state-store.ts`：版本化 payload、临时文件 + 原子改名 + fsync、属主
-* 可读、「认不出的内容一律读作没设过」。写入侧拒绝覆盖本版本读不懂的版本（ADR-006）。
+* 完整性三件套（与 provider / usage 同源，全部上收在 `state-store.ts`，本文件只做
+* 调用方——2026-10-17 收敛：此前这里**三件全缺**，并发 `saveEnabled` +
+* `saveModelId` 会丢一次保存、磁盘 version 比本构建新时降级覆写、读侧静默读作
+* 「没设过」，正是 provider-store 注释里记着「咬过三次」的那类漂移的第四条）：
+*   - **写串行化**（{@link createStateWriteQueue}）：读-改-写整体排队，临界区内
+*     从磁盘重读基线（不用 TTL 缓存—— provider §8d 的回归用例），链吞自己的
+*     失败继续走；
+*   - **写守卫**（{@link guardStateWrite}，ADR-006）：盘上版本本构建读不懂时
+*     拒写并给出理由，绝不降级覆写；「文件在场却读不出来」同样拒写（读不到 ≠
+*     没有东西要保护）；
+*   - **读侧说明**（{@link stateVersionNote}）：未知版本宽容读作「没设过」，但
+*     {@link createFileDrawStore} 的 `versionNote()` 把「保存的开关与模型偏好
+*     被忽略」说出口，快照聚合把它转进 `shapeWarnings`——不说，面板就把「保存的
+*     值被忽略」呈现成「从未保存过」。
+*
+* 与 provider-store 的一处**有意差异**：没有 legacy（pre-profile 共享目录）继承。
+* draw.json 随出图工具一起诞生，晚于按 profile 分段，市面上不存在共享布局里的
+* 旧 draw.json；provider.json 则需要（§23 之前它一直在共享目录）。
+*
+* doctor 覆盖：`describeDrawPayload` 给只读速览，`doctor.ts` 据此把 draw.json
+* 的「损坏 / 未知版本」报进症状表——写侧守卫挡覆盖，doctor 报静默降级。
 *
 * @module dsh-connect-modelscope-token-plan/draw-store
 */
@@ -2078,14 +2307,24 @@ 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
 };
-/** 本 build 读不读得懂这个版本。 */
+/**
+* 本 build 读不读得懂这个版本。
+*
+* 与 provider-store 的 {@link isKnownProviderVersion} 同形：**白名单**判据，
+* 不与 {@link DRAW_STORE_VERSION} 比较——升级后旧号仍要可读。读侧（parseAt）、
+* 报告侧（versionNote / describeDrawPayload）问的都是这一个函数，三者不可能就
+* 「什么是未知版本」说两套话。写侧问的是 `state-store` 的
+* `isKnownStateVersion`（它额外放行 `null` = 没有文件，那是唯一该写的情形）。
+* @param {unknown} version - 盘上读到的值（可能根本不是数字）。
+* @returns {boolean}
+*/
 function isKnownDrawVersion(version) {
-	return isKnownStateVersion(version, KNOWN_DRAW_VERSIONS);
+	return typeof version === "number" && KNOWN_DRAW_VERSIONS.includes(version);
 }
 /**
 * 归一一个保存的模型偏好：非空字符串，或 `null`（= 自动挑——具体挑谁由
@@ -2123,7 +2362,31 @@ function createFileDrawStore(options = {}) {
 	const { dir, profile = null, ttlMs = STATE_READ_TTL_MS, logger } = options;
 	const stateDir = drawStoreDir(profile, dir);
 	const filePath = join(stateDir, "draw.json");
-	/** 解析一份 payload；认不出的版本读作「没设过」但**记住**版本号。 */
+	/**
+	* 写一份补丁并落盘（内部用；对调用方暴露的是 saveEnabled / saveModelId / reset）。
+	*
+	* 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_DRAW_VERSIONS, {
+			label: "draw-state",
+			logger
+		});
+		if (refusal !== null) return refusal;
+		await ensureStateDir(stateDir);
+		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir, "draw.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;
@@ -2143,60 +2406,84 @@ function createFileDrawStore(options = {}) {
 	* 读当前 payload。
 	* @returns {Promise<DrawPayload>}
 	*/
-	const current = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD$1;
 	/**
-	* 写一份补丁并落盘。
-	* @param {{enabled?: boolean|null, modelId?: string|null}} patch - 要改的字段。
-	* @returns {Promise<string|null>} 拒绝原因（`null` = 已写入）。
+	* 读-改-写一份补丁，**整段排队**。
+	*
+	* 基线每次从磁盘重读（`parsePayload` 直读，不走 TTL 缓存）：两个 Host 进程
+	* 共享一个状态目录，而缓存里可能是写入前的值——provider §8d 的回归用例
+	* （两个写入者共享一个目录，回读把较新的缓存顶成旧值）在 draw 上同样成立。
+	* 写成功即 `cache.remember`，调用方不必各自回读一遍。
+	*
+	* 失败语义与 provider-store 对齐：拒绝原因与 IO 失败都**向上抛**（save 抛、
+	* 路由 catch 后 `respondError` 呈报），链自己吞掉失败继续走后面的保存。
+	*
+	* @param {{enabled?: boolean|null, modelId?: string|null}} patch - 要改的字段；
+	*   `undefined` = 保留盘上的值，`null` = 清除（回到「没设过」）。
+	* @returns {Promise<void>}
 	*/
-	const patchPayload = async (patch) => {
-		const before = await current();
-		const enabled = patch.enabled === void 0 ? before.enabled : patch.enabled;
-		const modelId = patch.modelId === void 0 ? before.modelId : patch.modelId;
-		try {
-			await ensureStateDir(stateDir);
-			const body = { version: 1 };
-			if (enabled !== null) body.enabled = enabled;
-			if (modelId !== null) body.modelId = modelId;
-			body.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-			await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir, "draw.json") });
-			cache.remember({
-				enabled,
-				modelId,
-				version: 1
-			});
-			return null;
-		} catch (error) {
-			return degrade("draw store write failed", error, logger, "draw store write failed");
-		}
-	};
+	const patchPayload = (patch) => writeQueue.enqueue(async () => {
+		const current = await parsePayload();
+		const enabled = patch.enabled === void 0 ? current.enabled : patch.enabled;
+		const modelId = patch.modelId === void 0 ? current.modelId : patch.modelId;
+		const body = { version: 1 };
+		if (enabled !== null) body.enabled = enabled;
+		if (modelId !== null) body.modelId = modelId;
+		body.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const refusal = await writePayload(body);
+		if (refusal !== null) throw new Error(refusal);
+		cache.remember({
+			enabled,
+			modelId,
+			version: 1
+		});
+	});
 	return {
 		/** 面板保存的出图开关；`null` = 回退 patch 默认值。 */
 		async enabled() {
-			return (await current()).enabled;
+			return (await readPayload()).enabled;
 		},
 		/** 面板保存的模型偏好；`null` = 自动。 */
 		async modelId() {
-			return (await current()).modelId;
+			return (await readPayload()).modelId;
 		},
 		/** 这个 profile 是否被显式配置过。 */
 		async isConfigured() {
-			const payload = await current();
+			const payload = await readPayload();
 			return payload.enabled !== null || payload.modelId !== null;
 		},
+		/**
+		* 盘上带着本构建读不懂的版本时的一句说明，否则 `null`。
+		*
+		* 读侧宽容（未知版本读作「没设过」）的另一半：快照聚合把它转进
+		* `shapeWarnings`，doctor 报同一份文件。没有它，「保存的开关与模型偏好
+		* 被忽略」在面板上就是「从未保存过」——而回退方向是 patch 默认（通常=关）。
+		* @returns {Promise<string|null>}
+		*/
+		async versionNote() {
+			const version = (await readPayload()).version;
+			if (version === null || isKnownDrawVersion(version)) return null;
+			return stateVersionNote({
+				label: "draw-state",
+				file: filePath,
+				version,
+				known: KNOWN_DRAW_VERSIONS,
+				consequence: "the saved draw switch and model preference are being answered as \"not set\", so the switch falls back to the config default and the model back to automatic selection."
+			});
+		},
 		/** 保存开关。 */
 		async saveEnabled(enabled) {
 			if (typeof enabled !== "boolean") throw new TypeError("draw switch expects a boolean");
-			return patchPayload({ enabled });
+			await patchPayload({ enabled });
 		},
 		/** 保存模型偏好（`null` = 清掉，回到自动）。 */
 		async saveModelId(modelId) {
 			if (modelId !== null && (typeof modelId !== "string" || modelId.trim() === "")) throw new TypeError("draw model expects a non-empty string or null");
-			return patchPayload({ modelId });
+			await patchPayload({ modelId });
 		},
 		/** 清掉两个字段（回到「没配过」）。 */
 		async reset() {
-			return patchPayload({
+			await patchPayload({
 				enabled: null,
 				modelId: null
 			});
@@ -2207,92 +2494,368 @@ function createFileDrawStore(options = {}) {
 }
 
 //#endregion
-//#region src/host/draw.ts
+//#region src/host/switch-precedence.ts
 /**
-* 魔搭出图（`/v1/images/generations`）的**纯逻辑半边**——协议形状的解析与判定。
-*
-* 为什么是这个形状：魔搭的生图是**异步两段式**（提交得 `task_id`，轮询才出图），
-* 与姊妹插件 `dsh-connect-sensenova-token-plan/src/host/draw.ts` 的**同步单发**
-* （`drawOnce` 一次 fetch 即 `parseDrawResponse` 取 `data[0].url`）形状不兼容，
-* **不能照抄**。可复用的只有外壳（endpoint 拼接、冷却门、失败文案），核心必须新写。
-* 协议依据全部来自 `docs/SPIKE-image-gen.md` 的真机实测，非文档转述。
-*
-* 本模块**只做纯函数**：endpoint 构造、请求体构造、响应解析、状态判定、失败分诊。
-* 它**不发起任何请求、不碰凭据、不注册工具**——那半边（fetch 注入、Host 工具注册）
-* 与 `llm-adapter.ts` 一样 peer-dependent，测试覆盖同样是零（docs/ROADMAP.md Backlog）。
-* 刻意 peer-free：纯函数部分能进离线 `npm test` 门禁，`test/draw.test.mjs` 钉住形状。
+* 所有 opt-in 开关共用的唯一裁决：「面板保存值 vs 配置默认值」。
 *
-* 三条承重结论（全部实测，推翻了几条广泛流传的错误写法）：
+* 规则只有一条：**面板保存值赢，否则配置默认值说了算**。来源标签（`panel` /
+* `config`）随答案一起返回，面板才能说出是谁在管。规则收在一处，是为了让开关
+* 再也无法各自发明一套优先级方言；`test/switch-precedence.test.mjs` 钉死这个
+* 方言，照抄形状的新调用方会被它标成异类。
 *
-* 1. **轮询必须带 `X-ModelScope-Task-Type: image_generation`**，否则上游一律返回
-*    `task not found` + `task_status: FAILED`——**那是假失败**，任务实际正常。
-*    缺这个头的实现会在第一次轮询就误判失败并放弃一张已经能出的图。
-* 2. **提交响应的 `task_status` 不可信**：实测每次提交都回 `SUCCEED`，包括最终确实
-*    `FAILED` 的那次。所以提交只认 `task_id`，**成功与否只看轮询终态**。
-* 3. **`FAILED` 没有可分诊的形状**：`errors.code` 实测为 `0`、`errors.message` 为
-*    空串，没有顶层 `message`。任何「从错误里读出原因」的承诺都是编造——本模块的
-*    `describeDrawFailure` 因此**明确承认原因不可知**，只报可确定的形态差异。
+* 不服务「纯面板拥有、无配置默认值」的开关——那种没有可裁决的配置默认值，
+* 调用方直接读即可。peer-free，纯函数。
 *
-* @module dsh-connect-modelscope-token-plan/draw
+* @module dsh-connect-modelscope-token-plan/switch-precedence
 */
 /**
-* 出图请求的截止时间（墙钟毫秒）。
-*
-* **15 分钟**：实测同一模型的耗时在 61s–537s 之间大幅波动（免费池排队），
-* 且**超时放弃不等于任务死亡**——上游任务会继续跑完（记录之后还会被回收，
-* 见 docs/SPIKE-image-gen.md §坑 5）。宁可多等，不要扔掉一张已在生成的图。
+* 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.
 */
-const DRAW_TIMEOUT_MS = 9e5;
+function resolveSwitchEnabled(panel, config) {
+	return (panel ?? config) === true;
+}
 /**
-* 两次轮询之间的间隔（毫秒）。
-*
-* 取 15s 的**真正理由**是「够用且不浪费」：实测最慢一次 537s，15s 间隔意味着
-* 最多几十次查询，代价可忽略；而更密（社区示例的 5s）没有观测收益。
-*
-* ⚠️ 早先曾写「更密的轮询拖慢任务」，**该归因已推翻**——后续对照显示同一模型、
-* 同样 15s 轮询的耗时是 61s → 261s → 537s 单调恶化，是**上游排队时长在波动**。
-* 那次构成「证据」的 5s vs 30s 对照，控制变量没做，不足以支撑因果。
-* 详见 docs/SPIKE-image-gen.md §坑 4（含撤回记录）。
+* 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.
 */
-const DRAW_POLL_INTERVAL_MS = 15e3;
-/** 轮询的总截止时间；与 `DRAW_TIMEOUT_MS` 同量级但独立可调（诊断时可放宽）。 */
-const DRAW_POLL_DEADLINE_MS = DRAW_TIMEOUT_MS;
+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.
 *
-* 漏掉它 → 上游返回 `task not found` + `FAILED`，而任务其实在正常跑。这是本协议
-* 最贵的单点知识，也是第一份外部资料缺失的那一块。
+* 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.
 */
-const TASK_TYPE_HEADER = "X-ModelScope-Task-Type";
-const TASK_TYPE_IMAGE_GENERATION = "image_generation";
+function resolveSwitchNumber(panel, config) {
+	return panel ?? config;
+}
 /**
-* 一次出图请求由几个 HTTP 请求组成：一次提交 + N 次轮询。
-* 只作为文档性常量，供工具描述与测试引用。
+* 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"}
 */
-const DRAW_PHASE = Object.freeze({
-	submit: "submit",
-	poll: "poll"
-});
+function switchSource(panel) {
+	return panel === null ? "config" : "panel";
+}
+
+//#endregion
+//#region src/host/usage-prefs-store.ts
 /**
-* 读一个响应的 `task_status`，取不到返回 `null`。
+* 用量面板的**显示偏好**——目前只有一个字段：趋势图的显示窗口（画多少天）。
 *
-* 刻意**不猜**：字段缺失或类型不对都返回 `null`，由 `isTerminalStatus` 把它当作
-* 「非终态」继续等——这样一次形状漂移最多变成多轮轮询，不会变成误报失败。
-* @param {unknown} data - 已解析的 JSON。
-* @returns {DrawTaskStatus|null} 规范化状态，取不到为 `null`。
+* ## 为什么单独一个文件
+*
+*  - `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
 */
-function readTaskStatus(data) {
-	if (data === null || typeof data !== "object") return null;
-	const raw = data.task_status;
-	if (typeof raw !== "string") return null;
-	const upper = raw.trim().toUpperCase();
-	if (upper === "PENDING" || upper === "RUNNING" || upper === "SUCCEED" || upper === "FAILED") return upper;
-	return null;
-}
+/** 本 store 落盘 payload 的版本。 */
+const USAGE_PREFS_VERSION = 1;
+/** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
+const KNOWN_USAGE_PREFS_VERSIONS = Object.freeze([1]);
+const EMPTY_PAYLOAD = {
+	windowDays: null,
+	version: null
+};
 /**
-* 一个状态是不是终态。
+* 本 build 读不读得懂这个版本。
 *
-* **只有** `SUCCEED` / `FAILED` 是终态；`null`（读不到）与一切未知值都**不是**。
+* 与 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
+/**
+* 魔搭出图（`/v1/images/generations`）的**纯逻辑半边**——协议形状的解析与判定。
+*
+* 为什么是这个形状：魔搭的生图是**异步两段式**（提交得 `task_id`，轮询才出图），
+* 与姊妹插件 `dsh-connect-sensenova-token-plan/src/host/draw.ts` 的**同步单发**
+* （`drawOnce` 一次 fetch 即 `parseDrawResponse` 取 `data[0].url`）形状不兼容，
+* **不能照抄**。可复用的只有外壳（endpoint 拼接、冷却门、失败文案），核心必须新写。
+* 协议依据全部来自 `docs/SPIKE-image-gen.md` 的真机实测，非文档转述。
+*
+* 本模块**只做纯函数**：endpoint 构造、请求体构造、响应解析、状态判定、失败分诊。
+* 它**不发起任何请求、不碰凭据、不注册工具**——那半边（fetch 注入、Host 工具注册）
+* 与 `llm-adapter.ts` 一样 peer-dependent，测试覆盖同样是零（docs/ROADMAP.md Backlog）。
+* 刻意 peer-free：纯函数部分能进离线 `npm test` 门禁，`test/draw.test.mjs` 钉住形状。
+*
+* 三条承重结论（全部实测，推翻了几条广泛流传的错误写法）：
+*
+* 1. **轮询必须带 `X-ModelScope-Task-Type: image_generation`**，否则上游一律返回
+*    `task not found` + `task_status: FAILED`——**那是假失败**，任务实际正常。
+*    缺这个头的实现会在第一次轮询就误判失败并放弃一张已经能出的图。
+* 2. **提交响应的 `task_status` 不可信**：实测每次提交都回 `SUCCEED`，包括最终确实
+*    `FAILED` 的那次。所以提交只认 `task_id`，**成功与否只看轮询终态**。
+* 3. **`FAILED` 没有可分诊的形状**：`errors.code` 实测为 `0`、`errors.message` 为
+*    空串，没有顶层 `message`。任何「从错误里读出原因」的承诺都是编造——本模块的
+*    `describeDrawFailure` 因此**明确承认原因不可知**，只报可确定的形态差异。
+*
+* 关于两个小工具（`str` / `redactSecrets`）：它们曾以**本地私有副本**的形式活在
+* 本文件里，理由是「避免为 3 行代码引 util 的依赖面」。那条理由不成立——util.ts
+* 自己只有 type-only import（peer-free），同包的 `draw-runtime.ts` 早就 import 它；
+* 而私有副本已经漂移：脱敏正则少了 `sk-` 与密码键值对两组、`ms-` 的 charset 与
+* util 版不一致（`[A-Za-z0-9-]` vs `[0-9a-f-]`）——脱敏闸漏一条就是凭据外泄
+* （红线 1）。现在一律用 util 的单一副本。
+*
+* @module dsh-connect-modelscope-token-plan/draw
+*/
+/**
+* 出图请求的截止时间（墙钟毫秒）。
+*
+* **15 分钟**：实测同一模型的耗时在 61s–537s 之间大幅波动（免费池排队），
+* 且**超时放弃不等于任务死亡**——上游任务会继续跑完（记录之后还会被回收，
+* 见 docs/SPIKE-image-gen.md §坑 5）。宁可多等，不要扔掉一张已在生成的图。
+*/
+const DRAW_TIMEOUT_MS = 9e5;
+/**
+* 两次轮询之间的间隔（毫秒）。
+*
+* 取 15s 的**真正理由**是「够用且不浪费」：实测最慢一次 537s，15s 间隔意味着
+* 最多几十次查询，代价可忽略；而更密（社区示例的 5s）没有观测收益。
+*
+* ⚠️ 早先曾写「更密的轮询拖慢任务」，**该归因已推翻**——后续对照显示同一模型、
+* 同样 15s 轮询的耗时是 61s → 261s → 537s 单调恶化，是**上游排队时长在波动**。
+* 那次构成「证据」的 5s vs 30s 对照，控制变量没做，不足以支撑因果。
+* 详见 docs/SPIKE-image-gen.md §坑 4（含撤回记录）。
+*/
+const DRAW_POLL_INTERVAL_MS = 15e3;
+/**
+* 一次**工具调用**里愿意等的时间（毫秒）。
+*
+* 出图工具是给 agent 用的，一次调用阻塞 = 一整轮对话被占住。15 分钟的总预算
+* （{@link DRAW_TIMEOUT_MS}）是「这张图值不值得继续等」的上限，不是「一次调用
+* 该不该堵住 agent」的上限——两者同一个数，就是把上游排队的代价转嫁成对话的
+* 停顿。
+*
+* 取 90s：实测耗时 61s–537s 大幅波动，90s 能一次拿完最快那一档（61s），而
+* 更慢的本来就必须分段查（见 `draw-runtime.ts` 的两段式工具）。再往上加只是
+* 把「等得久」换成「卡得久」，并不改变「慢的图要分几次查」这个事实。
+*/
+const DRAW_WAIT_BUDGET_MS = 9e4;
+/**
+* 轮询必须携带的头名与取值。
+*
+* 漏掉它 → 上游返回 `task not found` + `FAILED`，而任务其实在正常跑。这是本协议
+* 最贵的单点知识，也是第一份外部资料缺失的那一块。
+*/
+const TASK_TYPE_HEADER = "X-ModelScope-Task-Type";
+const TASK_TYPE_IMAGE_GENERATION = "image_generation";
+/**
+* 一次出图请求由几个 HTTP 请求组成：一次提交 + N 次轮询。
+* 只作为文档性常量，供工具描述与测试引用。
+*/
+const DRAW_PHASE = Object.freeze({
+	submit: "submit",
+	poll: "poll"
+});
+/**
+* 读一个响应的 `task_status`，取不到返回 `null`。
+*
+* 刻意**不猜**：字段缺失或类型不对都返回 `null`，由 `isTerminalStatus` 把它当作
+* 「非终态」继续等——这样一次形状漂移最多变成多轮轮询，不会变成误报失败。
+* @param {unknown} data - 已解析的 JSON。
+* @returns {DrawTaskStatus|null} 规范化状态，取不到为 `null`。
+*/
+function readTaskStatus(data) {
+	if (data === null || typeof data !== "object") return null;
+	const raw = data.task_status;
+	if (typeof raw !== "string") return null;
+	const upper = raw.trim().toUpperCase();
+	if (upper === "PENDING" || upper === "RUNNING" || upper === "SUCCEED" || upper === "FAILED") return upper;
+	return null;
+}
+/**
+* 一个状态是不是终态。
+*
+* **只有** `SUCCEED` / `FAILED` 是终态；`null`（读不到）与一切未知值都**不是**。
 * 「未知值继续等」是刻意的：把上游新增的状态误判成失败会丢掉一张已经能出的图，
 * 而误判成进行中最多多等几轮（受 `DRAW_POLL_DEADLINE_MS` 兜底）。
 * @param {DrawTaskStatus|null} status - 规范化状态。
@@ -2361,17 +2924,17 @@ function readOutputImages(data) {
 */
 function buildDrawBody(options) {
 	const body = {
-		model: strOrEmpty(options.model),
-		prompt: strOrEmpty(options.prompt)
+		model: str(options.model, ""),
+		prompt: str(options.prompt, "")
 	};
 	const imageUrl = normalizeImageUrlList(options.imageUrl);
 	if (imageUrl.length > 0) body.image_url = imageUrl;
-	const size = strOrEmpty(options.size);
+	const size = str(options.size, "");
 	if (size !== "") body.size = size;
 	if (Number.isFinite(options.steps)) body.steps = options.steps;
 	if (Number.isFinite(options.guidance)) body.guidance = options.guidance;
 	if (Number.isFinite(options.seed)) body.seed = options.seed;
-	const negativePrompt = strOrEmpty(options.negativePrompt);
+	const negativePrompt = str(options.negativePrompt, "");
 	if (negativePrompt !== "") body.negative_prompt = negativePrompt;
 	const loras = options.loras;
 	if (typeof loras === "string" && loras.trim() !== "") body.loras = loras.trim();
@@ -2438,9 +3001,9 @@ function describeDrawFailure(failure) {
 	if (status === 404) return `出图失败：HTTP 404 —— 端点或模型不存在（检查 apiBase 与模型 id）${tail}`;
 	if (status === 429) return `出图失败：HTTP 429 —— 上游限流，请稍后重试${tail}`;
 	if (status >= 500) return `出图失败：HTTP ${status} —— 上游服务异常，稍后重试${tail}`;
-	const cause = strOrEmpty(failure.cause);
+	const cause = str(failure.cause, "");
 	if (cause !== "") return `出图失败：${cause}${tail}`;
-	const taskStatus = strOrEmpty(failure.taskStatus);
+	const taskStatus = str(failure.taskStatus, "");
 	if (taskStatus === "FAILED") return "出图失败：上游任务 FAILED，但未给出失败原因（实测 errors.code=0、message 为空），换模型或稍后重试";
 	if (taskStatus !== "") return `出图失败：任务停在 ${taskStatus}（非终态），已超过截止时间`;
 	return `出图失败：上游未给出可诊断的失败信息${tail}`;
@@ -2471,13 +3034,61 @@ function createDrawCooldown(cooldownMs) {
 		}
 	};
 }
-/** 读一个字符串，否则空串（本地化的小工具，避免为 3 行代码再引 util 的依赖面）。 */
-function strOrEmpty(value) {
-	return typeof value === "string" ? value.trim() : "";
-}
-/** 凭据脱敏：出图失败消息可能带上游回显的 body，令牌不能随它进日志或面板。 */
-function redactSecrets(text) {
-	return text.replace(/(["']?[Aa]uthorization["']?\s*[:=]\s*["']?)(?!Bearer\s)[^"',;\s]+/g, "$1[REDACTED]").replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "$1 [REDACTED]").replace(/\bms-[A-Za-z0-9-]{16,}/g, "ms-[REDACTED]");
+
+//#endregion
+//#region src/host/draw-jobs.ts
+/**
+* 建一张出图作业表。
+* @param {DrawJobsOptions} [options] - 容量上限。
+* @returns {DrawJobs} 作业表。
+*/
+function createDrawJobs(options = {}) {
+	const maxJobs = Math.max(1, Math.floor(options.maxJobs ?? 64));
+	/** @type {Map<string, DrawJob>} 插入顺序即淘汰顺序（Map 保序）。 */
+	const jobs = /* @__PURE__ */ new Map();
+	const evictIfNeeded = () => {
+		while (jobs.size > maxJobs) {
+			const oldest = jobs.keys().next();
+			if (oldest.done === true) return;
+			jobs.delete(oldest.value);
+		}
+	};
+	return {
+		create({ taskId, model, prompt, now }) {
+			const jobId = taskId;
+			const job = {
+				jobId,
+				taskId,
+				model,
+				prompt,
+				submittedAt: typeof now === "number" && Number.isFinite(now) ? now : Date.now(),
+				polls: 0
+			};
+			const previous = jobs.get(jobId);
+			if (previous !== void 0) job.polls = previous.polls;
+			jobs.set(jobId, job);
+			evictIfNeeded();
+			return { ...job };
+		},
+		get(jobId) {
+			const found = jobs.get(jobId);
+			return found === void 0 ? null : { ...found };
+		},
+		notePolls(jobId, polls) {
+			const found = jobs.get(jobId);
+			if (found === void 0) return;
+			found.polls += Math.max(0, Math.floor(polls));
+		},
+		drop(jobId) {
+			jobs.delete(jobId);
+		},
+		dispose() {
+			jobs.clear();
+		},
+		size() {
+			return jobs.size;
+		}
+	};
 }
 
 //#endregion
@@ -2488,7 +3099,14 @@ function redactSecrets(text) {
 * 与 `llm-adapter.ts` 同一个处境——import Host 发行的 peer（`@deepseek-ai/dsh-tools`
 * 的 `defineTool` 由调用方惰性注入），**不能由离线单测套件导入**。纯逻辑全部住在
 * `draw.ts`（已由 `test/draw.test.mjs` 覆盖 39 组），本文件只做「接线 + I/O」：
-* 轮询循环、fetch、工具定义。改错本文件**不会让任何门禁变红**。
+* 轮询循环、fetch、工具定义。
+*
+* **覆盖边界**（2026-10-16 复核）：`runDrawOnce` / `pickDrawModel` / `drawModelIds` /
+* `splitImageUrls` / `buildGenerationsEndpoint` / `buildTasksEndpoint` /
+* `DRAW_TOOL_NAME` 由 `test/draw-runtime.test.mjs` 钉住；**没被覆盖的是
+* `defineDrawTool` 落到 peer registry 的那一段**（真 `defineTool` 形状与注册结果）
+* ——只改那一段不会让任何门禁变红。本文件此前整段自称「无覆盖」，该陈述在补上
+* 这个套件之后已经过时。
 *
 * 与姊妹插件的关键差异（形状不兼容，不能照抄）：
 * `sensenova` 的出图是**同步单发**——一次 `fetch` 拿 `data[0].url` 就结束。魔搭是
@@ -2507,19 +3125,6 @@ function redactSecrets(text) {
 */
 /** 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;
 /**
@@ -2559,28 +3164,16 @@ function isTerminalPayload(data) {
 	return isTerminalStatus(readTaskStatus(data));
 }
 /**
-* 真正跑一次出图：提交 + 轮询到终态。
+* **第一段**：提交一次出图，只要 `task_id`。
 *
-* 两段都必须带各自必需的头：提交带 `X-ModelScope-Async-Mode`（实测可省但官方示例
-* 都带，带上无害），轮询带 `X-ModelScope-Task-Type`（**必需**，漏了必假失败）。
-* @param {object} options - 调用参数。
-* @param {DrawFetch} options.fetchImpl - 注入的 fetch。
-* @param {string} options.apiBase - apiBase。
-* @param {string} options.apiKey - 访问令牌（绝不出现在返回文本里）。
-* @param {string} options.model - 模型 id。
-* @param {string} options.prompt - 提示词。
-* @param {string|string[]} [options.imageUrl] - 输入图（图生图 / 多图编辑）。
-* @param {string} [options.size] - `"宽x高"`。
-* @param {number} [options.steps] - 采样步数。
-* @param {number} [options.guidance] - 引导系数。
-* @param {number} [options.seed] - 种子。
-* @param {string} [options.negativePrompt] - 负向提示词。
-* @param {number} [options.pollDeadlineMs] - 轮询截止。
-* @param {number} [options.pollIntervalMs] - 轮询间隔（测试可缩短）。
-* @returns {Promise<DrawOutcome>} 出图结果。
-* @throws {Error} 提交失败、任务 FAILED、或超时——消息已过 `describeDrawFailure`。
+* 提交必须带 `X-ModelScope-Async-Mode`（实测可省但官方示例都带，带上无害）。
+* 响应里的 `task_status` **一律忽略**——实测恒为 `SUCCEED`，连最终 `FAILED` 的那次
+* 也是，所以成功与否只看轮询终态（这条由 `readTaskId` 钉在纯逻辑层）。
+* @param {DrawSubmitInput} input - 提交参数。
+* @returns {Promise<{taskId: string}>} 上游任务 id（= 续查用的 jobId）。
+* @throws {Error} 提交失败——消息已过 `describeDrawFailure`。
 */
-async function runDrawOnce({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl, size, steps, guidance, seed, negativePrompt, pollDeadlineMs = DRAW_POLL_DEADLINE_MS, pollIntervalMs = DRAW_POLL_INTERVAL_MS }) {
+async function submitDrawTask({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl, size, steps, guidance, seed, negativePrompt }) {
 	const headers = {
 		Authorization: `Bearer ${apiKey}`,
 		"Content-Type": "application/json"
@@ -2618,13 +3211,48 @@ async function runDrawOnce({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl
 		bodyText: submitText,
 		cause: "提交响应里没有 task_id"
 	}));
-	const deadline = Date.now() + Math.max(1e3, Math.floor(pollDeadlineMs));
+	return { taskId };
+}
+/**
+* **第二段**：在给定预算内轮询一个任务，直到终态或预算耗尽。
+*
+* 与 `runDrawOnce` 的差别只有一处：预算耗尽时**返回 `pending` 而不是抛错**——
+* 抛错是「这件事做不成了」，`pending` 是「还没成，可以再查」。同一段循环因此
+* 同时服务于两种调用形状（一次性跑完 / 分段续查），不写两份。
+*
+* 轮询带 `X-ModelScope-Task-Type`（**必需**，漏了必假失败）；传输层抖动与非
+* JSON 响应体都**不升级为终局**，继续等下一轮。
+* @param {object} options - 等待参数。
+* @param {DrawFetch} options.fetchImpl - 注入的 fetch。
+* @param {string} options.apiBase - apiBase。
+* @param {string} options.apiKey - 访问令牌。
+* @param {string} options.taskId - 上游任务 id。
+* @param {number} [options.waitMs] - 本次调用的等待预算。
+* @param {number} [options.pollIntervalMs] - 轮询间隔（测试可缩短）。
+* @returns {Promise<DrawAwait>} 三种结局之一。
+*/
+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"
+	};
+	const deadline = Date.now() + Math.max(1, Math.floor(waitMs));
 	const interval = Math.max(1, Math.floor(pollIntervalMs));
 	let polls = 0;
 	let lastStatus;
 	for (;;) {
-		if (Date.now() >= deadline) throw new Error(describeDrawFailure({ cause: `超过截止时间（${Math.round(pollDeadlineMs / 1e3)}s，${polls} 次轮询）仍未拿到结果。上游任务（${taskId}）**可能仍在生成**——实测排队时长在 1–15 分钟间大幅波动，与请求本身无关。稍后可重试；注意超时后原任务的结果不保证还能取回` }));
-		await sleep(interval);
+		if (Date.now() >= deadline) return {
+			kind: "pending",
+			polls
+		};
+		try {
+			await sleep(interval, signal);
+		} catch {
+			return {
+				kind: "pending",
+				polls
+			};
+		}
 		polls++;
 		let polled;
 		try {
@@ -2639,29 +3267,37 @@ async function runDrawOnce({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl
 			continue;
 		}
 		const pollText = await safeText(polled);
-		if (!polled.ok) throw new Error(describeDrawFailure({
-			...polled.status !== void 0 ? { status: polled.status } : {},
-			...pollText !== "" ? { bodyText: pollText } : {},
-			...lastStatus !== void 0 ? { taskStatus: lastStatus } : {}
-		}));
+		if (!polled.ok) return {
+			kind: "failed",
+			message: describeDrawFailure({
+				...polled.status !== void 0 ? { status: polled.status } : {},
+				...pollText !== "" ? { bodyText: pollText } : {},
+				...lastStatus !== void 0 ? { taskStatus: lastStatus } : {}
+			})
+		};
 		const data = await safeJson(polled, pollText);
 		const status = readTaskStatus(data);
 		if (status !== null) lastStatus = status;
 		if (!isTerminalPayload(data)) continue;
-		if (status === "FAILED") throw new Error(describeDrawFailure({
-			taskStatus: "FAILED",
-			bodyText: pollText
-		}));
+		if (status === "FAILED") return {
+			kind: "failed",
+			message: describeDrawFailure({
+				taskStatus: "FAILED",
+				bodyText: pollText
+			})
+		};
 		const images = readOutputImages(data);
-		if (images.length === 0) throw new Error(describeDrawFailure({
-			taskStatus: "SUCCEED",
-			bodyText: pollText,
-			cause: "任务报 SUCCEED 但没有可用图片"
-		}));
+		if (images.length === 0) return {
+			kind: "failed",
+			message: describeDrawFailure({
+				taskStatus: "SUCCEED",
+				bodyText: pollText,
+				cause: "任务报 SUCCEED 但没有可用图片"
+			})
+		};
 		return {
-			model,
+			kind: "done",
 			images,
-			taskId,
 			polls
 		};
 	}
@@ -2691,16 +3327,7 @@ async function runDrawOnce({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl
 * @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 与用户看到实际候选）。
@@ -2711,30 +3338,121 @@ function drawModelIds(entries) {
 	return imageGenModelIds(entries);
 }
 /**
-* 装配 agent 工具定义。
+* 装配 agent 工具定义——**两段式**，一次调用不再阻塞整轮对话。
+*
+* ## 为什么是两段式
 *
-* 工具只做「参数归一 → 跑一次 → 组装结果文本」，所有判定都委托给 `draw.ts` 的纯函数。
+* 上游出图要排队，实测 61s–537s（免费池）。旧形状是「一次调用 await 到终态」，
+* 于是 `drawTimeoutMs`（15 分钟）既是「这张图值不值得等」的上限，也成了「一轮
+* 对话被卡多久」的上限——把上游排队的代价直接转嫁成对话停顿。
+*
+* 现在一次调用只做两件事之一：
+*   - **不带 `jobId`** → 提交任务，然后只在 `waitMs`（默认 {@link DRAW_WAIT_BUDGET_MS}）
+*     内等；等到就返回 `done`，没等到就返回 `pending` + `jobId`；
+*   - **带 `jobId`** → 只查那个任务，同样最多等 `waitMs`。
+*
+* `drawTimeoutMs` 因此回到它本来的语义：**从提交算起的总放弃线**（跨调用累计），
+* 越过它才报「放弃」。
+*
+* ## 两个刻意的判定
+*
+*   - `pending` **不是失败**：不抛错、不进冷却门。它只表示「这次调用愿意等的时间里
+*     没等到」，进冷却就会把续查这条路堵死——那正是分段查询的目的所在。
+*   - 只有**真失败**（提交失败 / 上游 `FAILED` / 越过总放弃线）才 `cooldown.fail()`。
+*
+* 工具仍只做「参数归一 → 跑一次 → 组装结果文本」，所有判定都委托给 `draw.ts` 的纯函数。
 * @param {object} options - 装配参数。
 * @param {(definition: object) => unknown} options.defineTool - peer 的工厂。
 * @param {DrawFetch} options.fetchImpl - 注入的 fetch。
 * @param {() => Promise<string>} options.resolveApiKey - 每次调用现读令牌。
 * @param {() => unknown|Promise<unknown>} [options.getEntries] - 目录条目读取器。
-* @param {object} [options.settings] - `{ apiBase, drawModelId, drawTimeoutMs }`。
+* @param {object} [options.settings] - `{ apiBase, drawModelId, drawTimeoutMs, drawWaitMs }`。
 * @param {ReturnType<typeof createDrawCooldown>} [options.cooldown] - 冷却门。
+* @param {DrawJobs} [options.jobs] - 作业表（可注入，便于测试）。
 * @param {() => boolean} [options.isDisposed] - 卸载闸。
 * @returns {unknown} 已定义的 agent 工具。
 */
-function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, settings, getPreferredModelId, cooldown = createDrawCooldown(DRAW_FAILURE_COOLDOWN_MS), isDisposed = () => false }) {
+function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, settings, getPreferredModelId, cooldown = createDrawCooldown(DRAW_FAILURE_COOLDOWN_MS), jobs = createDrawJobs(), pollIntervalMs = DRAW_POLL_INTERVAL_MS, isDisposed = () => false }) {
+	/** 总放弃线：从提交算起，跨多次调用累计。 */
 	const timeoutMs = Math.max(3e4, Math.floor(Number(settings?.drawTimeoutMs) > 0 ? Number(settings?.drawTimeoutMs) : DRAW_TIMEOUT_MS));
+	/**
+	* 单次调用愿意等的时间。
+	*
+	* 只夹**上界**（不该超过总放弃线，超过它的等待没有意义）；下界交给
+	* `host-config` 的 `drawWaitMs` clamp——同一个数在两处各夹一次，上限/下限就会
+	* 各说一套话（`drawTimeoutMs` 的 clamp 早已是本仓库的教训）。
+	*/
+	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} 的三种结局翻译成工具结果或错误。
+	*
+	* 两段共用这一段——「刚提交的」与「续查的」在等待这件事上没有区别，唯一的区别
+	* 是作业表里那条记录从哪来。
+	* @param {string} apiKey - 访问令牌。
+	* @param {DrawJob} job - 作业（含提交时刻与累计轮询数）。
+	* @param {string[]} available - 目录里的出图模型（续查时为空，不必再拉目录）。
+	* @returns {Promise<DrawToolResult>} 工具结果。
+	* @throws {Error} 真失败（上游 FAILED / 轮询 HTTP 失败）或越过总放弃线。
+	*/
+	const waitAndReport = async (apiKey, job, available) => {
+		abortIfDisposed();
+		const awaited = await awaitDrawTask({
+			fetchImpl,
+			apiBase,
+			apiKey,
+			taskId: job.taskId,
+			waitMs,
+			pollIntervalMs,
+			signal: abortController.signal
+		});
+		if (awaited.kind === "failed") {
+			jobs.drop(job.jobId);
+			throw new Error(awaited.message);
+		}
+		jobs.notePolls(job.jobId, awaited.polls);
+		const polls = job.polls + awaited.polls;
+		if (awaited.kind === "done") {
+			jobs.drop(job.jobId);
+			const urls = awaited.images.join("\n");
+			return {
+				source: "modelscope",
+				status: "done",
+				jobId: job.jobId,
+				model: job.model,
+				url: awaited.images[0] ?? "",
+				prompt: job.prompt,
+				hint: `图片已生成（上游异步任务，${polls} 次轮询，task ${job.taskId}）\n模型: ${job.model}\n${urls}` + (available.length > 0 ? `\n可用出图模型: ${available.join(", ")}` : "")
+			};
+		}
+		const elapsedMs = Date.now() - job.submittedAt;
+		if (elapsedMs >= timeoutMs) throw new Error(describeDrawFailure({ cause: `超过总预算（${Math.round(timeoutMs / 1e3)}s，${polls} 次轮询）仍未拿到结果。上游任务（${job.taskId}）可能仍在生成——实测排队时长在 1–15 分钟间大幅波动，与请求本身无关；注意放弃后原任务的结果不保证还能取回` }));
+		return {
+			source: "modelscope",
+			status: "pending",
+			jobId: job.jobId,
+			model: job.model,
+			url: "",
+			prompt: job.prompt,
+			hint: `仍在生成中（已等 ${Math.round(elapsedMs / 1e3)}s，${polls} 次轮询，task ${job.taskId}）：上游排队通常 1–15 分钟。稍后带 jobId ${job.jobId} 再调用本工具即可继续查询（只查询、不会重复出图）`
+		};
+	};
 	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. This call is ASYNCHRONOUS upstream: the model queues first, so latency varies from ~1 minute to 15+ minutes depending on the free pool; it polls until the task reaches a terminal state. 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",
 				required: true,
-				description: "Image prompt; describe the target image (for edits, describe the intended change)"
+				description: "Image prompt; describe the target image (for edits, describe the intended change). Ignored when resuming with `jobId`."
+			},
+			jobId: {
+				type: "string",
+				description: "Resume an earlier task: pass the `jobId` returned by a previous call to keep polling it (no new image is submitted)"
 			},
 			model: {
 				type: "string",
@@ -2771,6 +3489,8 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 				additionalProperties: false,
 				properties: {
 					source: { type: "string" },
+					status: { type: "string" },
+					jobId: { type: "string" },
 					model: { type: "string" },
 					url: { type: "string" },
 					prompt: { type: "string" },
@@ -2782,15 +3502,26 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 				text: result?.hint || "图片已生成"
 			}]
 		},
-		timeoutMs: timeoutMs + 1e4,
+		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, "");
+			if (resumeId !== "") {
+				const job = jobs.get(resumeId);
+				if (job === null) throw new Error(`jobId ${resumeId} 不在本次会话的作业表里（插件重启过，或该 id 不是本插件发出的）：原任务可能仍在生成，但它的结果不保证还能取回（上游终态记录会被回收），请重新出图`);
+				try {
+					return await waitAndReport(apiKey, job, []);
+				} catch (error) {
+					cooldown.fail();
+					throw error;
+				}
+			}
 			const prompt = str(params?.prompt, "");
 			if (prompt === "") throw new Error("prompt is required");
 			const remaining = cooldown.remainingMs();
 			if (remaining > 0) throw new Error(`draw cooldown: 上一次出图失败，${Math.ceil(remaining / 1e3)}s 后再试`);
-			const apiKey = await resolveApiKey();
-			if (typeof apiKey !== "string" || apiKey.trim() === "") throw new Error("MODELSCOPE_API_KEY 未配置：在面板粘贴 ms- 访问令牌，或设置该环境变量");
 			let picked = [];
 			try {
 				picked = await getEntries?.() ?? [];
@@ -2816,7 +3547,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 				const guidance = toPositiveNumber(params?.guidance);
 				const seed = toNonNegativeInt(params?.seed);
 				const negativePrompt = str(params?.negativePrompt, "");
-				const outcome = await runDrawOnce({
+				const { taskId } = await submitDrawTask({
 					fetchImpl,
 					apiBase,
 					apiKey,
@@ -2827,18 +3558,14 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 					...steps !== void 0 ? { steps } : {},
 					...guidance !== void 0 ? { guidance } : {},
 					...seed !== void 0 ? { seed } : {},
-					...negativePrompt !== "" ? { negativePrompt } : {},
-					pollDeadlineMs: timeoutMs
+					...negativePrompt !== "" ? { negativePrompt } : {}
 				});
-				const available = drawModelIds(entries);
-				const urls = outcome.images.join("\n");
-				return {
-					source: "modelscope",
-					model: outcome.model,
-					url: outcome.images[0] ?? "",
-					prompt,
-					hint: `图片已生成（上游异步任务，${outcome.polls} 次轮询，task ${outcome.taskId}）\n模型: ${outcome.model}\n${urls}` + (available.length > 0 ? `\n可用出图模型: ${available.join(", ")}` : "")
-				};
+				const job = jobs.create({
+					taskId,
+					model,
+					prompt
+				});
+				return await waitAndReport(apiKey, job, drawModelIds(entries));
 			} catch (error) {
 				cooldown.fail();
 				throw error;
@@ -2895,82 +3622,56 @@ async function safeJson(response, text) {
 		}
 	}
 }
-/** 可注入的 sleep（测试可覆写；这里只提供默认实现）。 */
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-//#endregion
-//#region src/host/draw-tool-state.ts
-/** 当前缺席原因（`null` = 未登记 / 已清掉）。 */
-let note = null;
 /**
-* 记下缺席原因（`null` 清空）。
-* @param {DrawToolAbsentReason|null} reason - 原因码。
-* @returns {void}
-*/
-function setDrawToolNote(reason) {
-	note = reason;
-}
-/**
-* 读当前缺席原因。
-* @returns {DrawToolAbsentReason|null} 原因码。
-*/
-function drawToolNote() {
-	return note;
-}
-/**
-* 清空（卸载时调用：下一个 Host 生命周期从干净的「未登记」开始）。
-* @returns {void}
+* 可注入的 sleep（测试可覆写；这里只提供默认实现）。
+*
+* 支持 `AbortSignal`：插件 dispose 时可以立即中断等待，而不是等 sleep 自然结束。
+* 默认 15s 的轮询间隔意味着用户点「停止」后最多要等 15s 才真正停——abort 让
+* 停止信号立即生效。
 */
-function resetDrawToolNote() {
-	note = null;
+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
-//#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
-*/
+//#region src/host/draw-tool-state.ts
+/** 当前缺席原因（`null` = 未登记 / 已清掉）。 */
+let note = null;
 /**
-* 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.
+* 记下缺席原因（`null` 清空）。
+* @param {DrawToolAbsentReason|null} reason - 原因码。
+* @returns {void}
 */
-function resolveSwitchEnabled(panel, config) {
-	return (panel ?? config) === true;
+function setDrawToolNote(reason) {
+	note = reason;
 }
 /**
-* 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.
+* 读当前缺席原因。
+* @returns {DrawToolAbsentReason|null} 原因码。
 */
-function resolveSwitchValue(panel, config) {
-	return panel ?? config;
+function drawToolNote() {
+	return note;
 }
 /**
-* 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"}
+* 清空（卸载时调用：下一个 Host 生命周期从干净的「未登记」开始）。
+* @returns {void}
 */
-function switchSource(panel) {
-	return panel === null ? "config" : "panel";
+function resetDrawToolNote() {
+	note = null;
 }
 
 //#endregion
@@ -2993,9 +3694,16 @@ function switchSource(panel) {
 * registry 拒收——三种都由 `draw-tool-state.ts` 记下原因供面板显示。本文件不吞
 * 错误（那会让「工具为什么不在」无从诊断），只把它们翻译成可展示的原因码。
 *
-* peer-dependent：`@deepseek-ai/dsh-tools` 由 `deps.loadToolsModule` 惰性注入，
-* 因此本文件与 `llm-adapter.ts` 一样**不能被离线测试导入**，也没有测试覆盖
-* （docs/ROADMAP.md Backlog 记着这条缺口）。
+* peer-dependent：`@deepseek-ai/dsh-tools` 由 `deps.loadToolsModule` 惰性注入。
+*
+* **测试覆盖**：`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
 */
@@ -3046,7 +3754,7 @@ async function registerDrawTool(ctx, wiring, deps = {}) {
 			defineTool = mod?.defineTool ?? mod?.default?.defineTool ?? null;
 		} catch (error) {
 			setDrawToolNote("peer-load-failed");
-			loggerFor?.warn?.(`${name}: draw tool peer module failed to load (${redactSecrets$1(errMsg(error))}) — the tool is absent`);
+			loggerFor?.warn?.(`${name}: draw tool peer module failed to load (${redactSecrets(errMsg(error))}) — the tool is absent`);
 			return;
 		}
 		if (typeof defineTool !== "function") {
@@ -3068,13 +3776,14 @@ async function registerDrawTool(ctx, wiring, deps = {}) {
 			settings: {
 				apiBase: settings.apiBase,
 				drawModelId: settings.drawModelId,
-				drawTimeoutMs: settings.drawTimeoutMs
+				drawTimeoutMs: settings.drawTimeoutMs,
+				drawWaitMs: settings.drawWaitMs
 			},
 			isDisposed
 		}));
 	} catch (error) {
 		setDrawToolNote("registry-refused");
-		loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets$1(errMsg(error))}) — the tool is absent`);
+		loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets(errMsg(error))}) — the tool is absent`);
 	}
 }
 
@@ -3265,7 +3974,7 @@ function describeBuildFailure(error) {
 	const annotated = error;
 	const why = errMsg(error);
 	return {
-		note: redactSecrets$1(why),
+		note: redactSecrets(why),
 		hint: annotated?.code === "ERR_MODULE_NOT_FOUND" ? " — the llm peer packages ship with the Host; install this plugin where they resolve (or link them into its own node_modules)" : "",
 		error
 	};
@@ -3371,7 +4080,7 @@ function swapRegistration({ llm, built, previousBuilt, state, release, registerP
 		release();
 		state.built = null;
 		onRollback?.();
-		state.error = redactSecrets$1(errMsg(error));
+		state.error = redactSecrets(errMsg(error));
 		restorePreviousPair({
 			llm,
 			previousBuilt,
@@ -3450,9 +4159,20 @@ function emitAdaptersUpdated(emit) {
 *   - 单点 `registerPair`（带 factory-await + shape 检查）被 publish 与 rollback
 *     两条路共用；失败时**恢复旧对**，坏 publish 不会把已在服务的模型也拉下来。
 *
-* 与姊妹插件的差异**只有**：工厂导出名 `"createModelScopeAdapter"`、`registerPair`
-* 用的 `LLM_PROVIDER_ID`/`LLM_DISPLAY_NAME`、`warnBuildFailure` 的 label
-* `"ModelScope"`。上面的四条语义原样保留——它们是 `publish-core.ts` 的骨头。
+* 结构性纪律（本文件新立的）：一次 publish 拆成 **gather（可挂起）**与
+* **commit（不可挂起）**两半，commit 是**非 async 函数**——「disposed 复查与
+* registerAdapter 之间没有 await」由此前的注释论证升级为语言级保证。相位
+* （idle/serving/failing/broken/disposed）从契约字段推导，不双写。
+*
+* 与 sensenova 版的关系：**结构同源、代码不等价**——去注释后代码行重叠 77%
+* （2026-10-16 实测；复核：`node tools/dev/cross-repo-drift.mjs`）。所以差异**不止**
+* 三个标签：除工厂导出名 `"createModelScopeAdapter"`、`registerPair` 用的
+* `LLM_PROVIDER_ID`/`LLM_DISPLAY_NAME`、`warnBuildFailure` 的 label `"ModelScope"`
+* 之外，vision 判定这里取自 `llm-models.ts`（sensenova 侧走 `parsers.ts` 的
+* `identifyVisionModel`），usage 观察层的接线位置也不同。
+*
+* 可以跨仓库**对着读**的是三条承重语义（队列 / disposed 闸 / 单点 registerPair，
+* 它们是 `publish-core.ts` 的骨头，三处 91% 同源）；具体代码不可照搬。
 *
 * peer-free：不 import 任何运行时 peer。适配器工厂由调用方注入
 * （`loadAdapterModule`，默认 `import("./llm-adapter.ts")`），所以离线套件可以换
@@ -3464,6 +4184,29 @@ function emitAdaptersUpdated(emit) {
 * @module dsh-connect-modelscope-token-plan/provider-publish
 */
 /**
+* 从 publisher 的契约状态**推导**相位——单源，不双写。
+*
+* `registered` / `error` 是 `publish-core.ts` 的共享契约字段（`swapRegistration`
+* 与 `unregister` 直接写它们）。并行维护一个 `phase` 字段就是双写，双写必然
+* 漂移且方向静默；推导让相位永远不可能与那两个字段矛盾。
+*
+* 相位与两道空转守卫的对应（旧版注释里的条件，现在是有名字的状态）：
+*   - `idle`     = 没注册且无错：开关关着的稳态 → 关侧空转守卫可跳过；
+*   - `serving`  = 已注册且无错：offer 已 live → 开侧空转守卫可跳过；
+*   - `failing`  = 已注册但有错：回滚到了旧对、但新 offer 没落地 → **必须继续
+*     重试**（跳过就是静默丢弃用户刚保存的清单）；
+*   - `broken`   = 没注册且有错：上次发布失败且什么都没在服务 → 继续重试自愈；
+*   - `disposed` = 插件已 dispose：任何 publish 都是 no-op。
+* @param {{registered: boolean, error: string|null}} state - publisher 状态。
+* @param {boolean} disposed - publish 队列的 disposed 闸状态。
+* @returns {PublisherPhase} 相位。
+*/
+function publisherPhaseOf(state, disposed) {
+	if (disposed) return "disposed";
+	if (state.registered) return state.error === null ? "serving" : "failing";
+	return state.error === null ? "idle" : "broken";
+}
+/**
 * provider 发布器。
 *
 * 持有活注册状态（`state`）；publish 队列、`disposed` 闸与单点 `registerPair` 是
@@ -3544,20 +4287,37 @@ function createProviderPublisher(deps = {}) {
 	*/
 	const offerUnchanged = () => state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds);
 	/**
-	* 为一个目录/允许清单快照（重）构建并注册 provider。
+	* 发布相位——两道空转守卫的判断条件从此有名字（推导见 {@link publisherPhaseOf}）。
+	* @param {boolean} disposed - 当前是否已 dispose。
+	* @returns {PublisherPhase}
+	*/
+	const phaseOf = (disposed) => publisherPhaseOf(state, disposed);
+	/**
+	* gather 阶段：一次 publish 的**可挂起**半边。
 	*
-	* 重建并重注册而非原地改：`PiAiAdapter` 内部 memoize profiles 快照，只有新的注册
-	* 才能改变提供的模型列表。注册失败时**恢复上一对**，所以坏 publish 永远不能把
-	* 已在服务的模型拉下来。
-	* @param {object[]} entries - 归一目录条目。
-	* @param {string[]} enabledIds - 允许清单（空 = 全部）。
-	* @param {string[]} [unavailableModelIds] - 要从 picker 的 offer 里丢掉的额度耗尽 id。
-	* @returns {Promise<{ok: boolean, skipped?: boolean, error?: unknown}>}
+	* 读面板开关、解析 llm 服务、解析适配器工厂、构建适配器——四个 await 全住
+	* 在这里。产出两种计划：`done`（跳过 / 注销 / 构建失败，都已执行完）或
+	* `commit`（适配器构建好了，只剩同步提交）。
+	*
+	* 领域字段（entries / enabledIds / unavailableIds）在查询开关**之前**写入，
+	* 开关关分支刻意不回滚它们——这个不对称是承重的，不是疏忽：`routes/provider.ts`
+	* 与 roster 保存会在开关重新打开时正好从这些字段重新 publish，所以用户的
+	* 允许清单编辑与最后一次拉到的目录**必须**熬过关闭期。把 `previous*` 还回去
+	* 会静默丢掉两者——开关关闭期间做的保存，会在开关重新打开时消失。
+	* `swapRegistration` 的 `onRollback` 会还它们，但只对注册真的抛了的路径——
+	* 那种失败必须让先前在服务的对继续服务，这是与「开关关着」不同的承诺。
+	* @param {unknown} entries - 归一目录条目。
+	* @param {unknown} enabledIds - 允许清单（空 = 全部）。
+	* @param {string[]} unavailableModelIds - 额度耗尽的模型 id。
+	* @returns {Promise<PublishPlan>} 执行计划。
 	*/
-	const publishProviderOnce = async (entries, enabledIds, unavailableModelIds = []) => {
+	const gatherPublish = async (entries, enabledIds, unavailableModelIds) => {
 		if (queue.isDisposed()) return {
-			ok: false,
-			skipped: true
+			kind: "done",
+			result: {
+				ok: false,
+				skipped: true
+			}
 		};
 		const previousBuilt = state.built;
 		const previousEntries = state.entries;
@@ -3568,16 +4328,22 @@ function createProviderPublisher(deps = {}) {
 		state.unavailableIds = Array.isArray(unavailableModelIds) ? unavailableModelIds : [];
 		const panelValue = await effectivePanelSwitch().catch(() => null);
 		if (!resolveSwitchEnabled(panelValue, effectiveSettings.registerProvider === true)) {
-			if (state.registered === false && state.error === null && offerUnchanged()) return {
-				ok: true,
-				skipped: true
+			if (phaseOf(false) === "idle" && offerUnchanged()) return {
+				kind: "done",
+				result: {
+					ok: true,
+					skipped: true
+				}
 			};
 			const result = unregister({
 				state,
 				release
 			});
 			syncSignaturesAfterPublish(state);
-			return result;
+			return {
+				kind: "done",
+				result
+			};
 		}
 		const llm = resolveRegistrationService({
 			state,
@@ -3585,13 +4351,15 @@ function createProviderPublisher(deps = {}) {
 			release
 		});
 		if (llm === null) return {
-			ok: false,
-			error: state.error
+			kind: "done",
+			result: {
+				ok: false,
+				error: state.error
+			}
 		};
-		let createModelScopeAdapter;
 		let built;
 		try {
-			createModelScopeAdapter = await resolveAdapterFactory();
+			const createModelScopeAdapter = await resolveAdapterFactory();
 			if (createModelScopeAdapter === void 0) throw new Error(BAD_FACTORY_SHAPE_ERROR);
 			built = await createModelScopeAdapter({
 				entries: state.entries,
@@ -3600,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) {
@@ -3608,31 +4377,75 @@ function createProviderPublisher(deps = {}) {
 			state.error = described.note;
 			warnBuildFailure(effectiveLogger, "ModelScope", described);
 			return {
-				ok: false,
-				error: described.error
+				kind: "done",
+				result: {
+					ok: false,
+					error: described.error
+				}
 			};
 		}
-		if (state.registered === true && state.error === null && offerUnchanged()) return {
-			ok: true,
-			skipped: true
+		if (phaseOf(false) === "serving" && offerUnchanged()) return {
+			kind: "done",
+			result: {
+				ok: true,
+				skipped: true
+			}
+		};
+		return {
+			kind: "commit",
+			llm,
+			built,
+			previousBuilt,
+			previousEntries,
+			previousEnabledIds,
+			previousUnavailable
 		};
+	};
+	/**
+	* commit 阶段：一次 publish 的**不可挂起**半边。
+	*
+	* **这个函数刻意不是 `async`**——语言禁止在非 async 函数里写 `await`，所以
+	* 从下面的 disposed 复查到 `swapRegistration` 内部的 `registerAdapter` 之间
+	* **不可能**插入挂起点。旧版靠一句「这个位置严密：从这里到 registerAdapter
+	* 之间没有任何 await」的注释论证这件事；现在由函数签名本身保证——想在这里
+	* 加 await，编译期就过不去。临界区的正确性由结构承载，不由注释承载。
+	*
+	* 为什么这道复查必须有（gather 入口那次只覆盖到第一个 await，而注册发生在
+	* **最后一次** await 之后）：teardown 落在这段窗口里时，入口闸门不会重跑，
+	* 于是 registerAdapter 把适配器注册进一个**已经把本插件撤下的 Host**，而
+	* teardown 早就跑完、release 永不调用——泄漏的对持有 tokenStore 与整个
+	* Cordis ctx 的闭包，形成僵尸 provider：picker 里那个 provider 还在、还能
+	* 路由，而面板路由已注销，用户没有界面能关掉它。
+	*
+	* 为什么 peer 的 fiber 兜底救不了：`registerAdapter` 用的是 **llm 服务自己的**
+	* `ctx.effect`（peer 源码里 `.bind(this)` 到 llm 服务），插件卸载不会 dispose
+	* 它，宿主注册表永久持有该 adapter。
+	*
+	* 若 teardown 发生在本次检查**之后**，它执行 release() 时能看到新写入的
+	* releaseAdapter 并摘掉——两种时序都正确。检查刻意留在本文件（publisher）而
+	* **不**放进 `swapRegistration`：那是 publish-core 的共享骨头，不该知道
+	* disposed 的概念。
+	* @param {Extract<PublishPlan, {kind: "commit"}>} plan - gather 产出的提交计划。
+	* @returns {{ok: boolean, skipped?: boolean, error?: unknown}}
+	*/
+	const commitPublish = (plan) => {
 		if (queue.isDisposed()) return {
 			ok: false,
 			skipped: true
 		};
 		const requestedSignature = catalogSignature(state.entries, state.enabledIds);
 		const result = swapRegistration({
-			llm,
-			built,
-			previousBuilt,
+			llm: plan.llm,
+			built: plan.built,
+			previousBuilt: plan.previousBuilt,
 			state,
 			release,
 			registerPair,
 			emit,
 			onRollback: () => {
-				state.entries = previousEntries;
-				state.enabledIds = previousEnabledIds;
-				state.unavailableIds = previousUnavailable;
+				state.entries = plan.previousEntries;
+				state.enabledIds = plan.previousEnabledIds;
+				state.unavailableIds = plan.previousUnavailable;
 			}
 		});
 		syncSignaturesAfterPublish(state);
@@ -3640,6 +4453,22 @@ function createProviderPublisher(deps = {}) {
 		return result;
 	};
 	/**
+	* 为一个目录/允许清单快照（重）构建并注册 provider。
+	*
+	* 形状 = gather（可挂起）+ commit（不可挂起）：全部 await 住在前者，后者是
+	* 非 async 函数。重建并重注册而非原地改：`PiAiAdapter` 内部 memoize profiles
+	* 快照，只有新的注册才能改变提供的模型列表。注册失败时**恢复上一对**，所以
+	* 坏 publish 永远不能把已在服务的模型拉下来。
+	* @param {object[]} entries - 归一目录条目。
+	* @param {string[]} enabledIds - 允许清单（空 = 全部）。
+	* @param {string[]} [unavailableModelIds] - 要从 picker 的 offer 里丢掉的额度耗尽 id。
+	* @returns {Promise<{ok: boolean, skipped?: boolean, error?: unknown}>}
+	*/
+	const publishProviderOnce = async (entries, enabledIds, unavailableModelIds = []) => {
+		const plan = await gatherPublish(entries, enabledIds, unavailableModelIds);
+		return plan.kind === "done" ? plan.result : commitPublish(plan);
+	};
+	/**
 	* publish，排到所有其他在途 publish 之后。
 	*
 	* 包装的存在是为了没有任何调用方要记得队列：挂载 seed、目录轮询、provider 开关、
@@ -3669,6 +4498,10 @@ function createProviderPublisher(deps = {}) {
 * 它只回答「重建会不会改变什么」：目录顺序里的模型 id，每个带上 descriptor 用的
 * 同一个 vision 判定（id 没变但模态翻了也必须重建），加上允许清单。目录条目里其他
 * 东西变了不影响注册的 offer。
+*
+* **不含展示名 `name`**：模型展示名变化不影响注册的 offer（descriptor 里的 `name`
+* 只是显示用的），重新注册是浪费——期间在途请求可能被打断。展示名变化不改变
+* 模型的能力、窗口或输出上限，所以不参与签名。
 * @param {object[]} entries - 归一目录条目。
 * @param {string[]} enabledIds - 允许清单（空 = 全部）。
 * @returns {string}
@@ -3676,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(",")}`;
 }
 /**
@@ -3713,6 +4545,127 @@ function syncSignaturesAfterPublish(state) {
 	state.quotaSignature = quotaSignatureOf(unavailable);
 }
 
+//#endregion
+//#region src/host/provider-reconcile.ts
+/**
+* provider 注册的 **desired-state reconciler**——把两个各自为政的驱动收编成
+* 一个控制器。
+*
+* ## 它取代什么
+*
+* 改之前，往同一个注册态里写的有两个 driver：挂载 seed + 每 `pollSeconds`
+* 一次的目录轮询（`index.ts` 的 `runPoll`），以及四条 provider 路由的
+* 「保存后立即 publish」。两者没有共同的状态词汇表，于是 `runPoll` 不得不把
+* 窗口覆盖**读两遍**（fetch 前一次、fetch 后一次），「期间被改就跳过本轮」——
+* 那是没有 desired-state 控制器的典型补丁：丢一次更新、再等一个轮询周期。
+*
+* ## 模型
+*
+*   - **desired state**（操作者想要什么）= `providerStore` 里的开关 + 允许
+*     清单 + 窗口覆盖。它只有一个家，轮询和路由都只读它、不各写一份；
+*   - **reconcile 一遍** = 读 desired → 带窗口覆盖拉目录 → 复查 desired
+*     （fetch 期间被改就重跑，不等下一轮）→ 把「当前目录 + 当前清单」交给
+*     publisher（它自己重读开关，single source 不变）；
+*   - **触发方全部降级为「标记 dirty」**：挂载、轮询定时器、四条写路由。
+*     谁都不用记得「别人是不是也在 publish」——队列性质由本模块的串行链保证。
+*
+* ## 两个刻意的行为改变（相对旧 runPoll）
+*
+*   1. **fetch 失败不再发布空目录**。旧 `readEntries` 把 fetch 失败降级成
+*      `entries: []` 再 publish——一次瞬时的目录抖动会把已服务的模型全部撤下
+*      （破坏，不是重试）。这里失败只记原因、保留当前 offer，下一轮自然重试；
+*      轮询侧本来就该如此（旧 runPoll 正是这么做的），路由侧现在与它一致。
+*   2. **fetch 期间 desired 被改 → 重跑，不是跳过**。旧代码「跳过本轮、等
+*      pollSeconds」；这里原地收敛，保存路由的 await 返回时新值一定已落地。
+*
+* peer-free：不 import 任何 Host peer。
+*
+* @module dsh-connect-modelscope-token-plan/provider-reconcile
+*/
+/**
+* 创建 provider reconciler。
+*
+* 串行链 + dirty 标志：每次触发（轮询/路由/挂载）都排在链尾，链上每一环先看
+* dirty 再决定要不要真跑——在途那一轮会替后来者消费 dirty，所以 N 次连续触发
+* 最多收敛成两遍 reconcile，不会排 N 遍。调用方 await 返回的 promise，即
+* 「我的触发已被消费」。
+* @param {ProviderReconcilerDeps} deps - wiring 子集。
+* @returns {{reconcile: () => Promise<void>}} 触发一次收敛。
+*/
+function createProviderReconciler(deps) {
+	const { providerStore, inference, publisher, logger } = deps;
+	/**
+	* 读一次 desired。三路都 `.catch(() => null)`：读不到按「未设置」降级，
+	* 与开关/清单/覆盖各自的读侧纪律一致——一次读失败不该把收敛打掉。
+	* @returns {Promise<Desired>}
+	*/
+	const readDesired = async () => {
+		const [enabled, enabledIds, contextWindow] = await Promise.all([
+			providerStore.enabled().catch(() => null),
+			providerStore.enabledIds().catch(() => null),
+			providerStore.contextWindow().catch(() => null)
+		]);
+		return {
+			enabled,
+			enabledIds,
+			contextWindow
+		};
+	};
+	/** desired 的稳定键：用于「fetch 期间被改了吗」的比对。 */
+	const desiredKey = (desired) => JSON.stringify([
+		desired.enabled,
+		desired.enabledIds,
+		desired.contextWindow
+	]);
+	/**
+	* 收敛一遍：读 desired → 拉目录 → 复查 desired → publish。
+	* @returns {Promise<void>}
+	*/
+	const runOnce = async () => {
+		const before = await readDesired();
+		let catalog;
+		try {
+			catalog = await inference.fetchModels(before.contextWindow);
+		} catch (error) {
+			logger?.warn?.(`${name}: catalog fetch failed (${redactSecrets(errMsg(error))}) — the current offer stays registered; the next pass retries`);
+			return;
+		}
+		const after = await readDesired();
+		if (desiredKey(after) !== desiredKey(before)) {
+			dirty = true;
+			return;
+		}
+		const entries = Array.isArray(catalog?.entries) ? catalog.entries : [];
+		const enabledIds = resolveEnabledIds(after.enabledIds, publisher.state.enabledIds);
+		try {
+			await publisher.publish(entries, enabledIds, []);
+		} catch (error) {
+			logger?.warn?.(`${name}: publish failed (${redactSecrets(errMsg(error))}) — the catalog is current, only the provider registration did not land`);
+		}
+	};
+	/** 串行链：每次触发排到链尾；在途那一轮替后来者消费 dirty。 */
+	let chain = Promise.resolve();
+	/** 有新触发待消费。闭包状态，不暴露——触发方只看得见 {@link reconcile}。 */
+	let dirty = false;
+	/**
+	* 触发一次收敛。幂等且可重入：在途时只置 dirty，由在途那一轮替本调用消费
+	* （N 次连续触发最多收敛成两遍 reconcile，不会排 N 遍）。
+	* @returns {Promise<void>} 本触发已被消费（注册态已反映 desired）后 resolve。
+	*/
+	const reconcile = () => {
+		dirty = true;
+		return chain = chain.then(async () => {
+			let guard = 0;
+			while (dirty) {
+				dirty = false;
+				await runOnce();
+				if (++guard > 20) break;
+			}
+		});
+	};
+	return { reconcile };
+}
+
 //#endregion
 //#region src/host/routes/paths.ts
 /**
@@ -3729,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
@@ -3767,38 +4721,21 @@ async function soft(promise) {
 		const code = error.code;
 		return {
 			ok: false,
-			error: redactSecrets$1(errMsg(error)),
+			error: redactSecrets(errMsg(error)),
 			code: typeof code === "string" ? code : CODE.INTERNAL_ERROR
 		};
 	}
 }
-/**
-* Provider 状态块降级形状：读不到开关/注册状态/目录时，面板仍然得到一个完整
-* 可渲染的块（开关关、roster 空、error 说明原因），绝不让整条快照失败。
-*/
-function providerDegraded(error) {
-	return {
-		enabled: false,
-		source: "config",
-		llmAvailable: false,
-		registered: false,
-		error,
-		modelCount: 0,
-		enabledCount: 0,
-		allowed: "all",
-		enabledIds: [],
-		contextWindow: null,
-		roster: []
-	};
-}
 /** 聚合快照 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())
 	]);
@@ -3820,6 +4757,14 @@ async function buildSnapshotBody(wiring) {
 	if (!models.ok && models.code !== "network_error") shapeWarnings.push(`models: ${models.error}`);
 	if (!tokenKnownAbsent && !balance.ok && balance.code !== "network_error") shapeWarnings.push(`balance: ${balance.error}`);
 	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);
@@ -3827,10 +4772,9 @@ async function buildSnapshotBody(wiring) {
 		const roster = rosterWithAvailability(modelEntries, []);
 		const stored = await providerStore.enabledIds().catch(() => null);
 		const enabledIds = resolveEnabledIds(stored, publisher.state.enabledIds);
+		const allowedList = parseAllowedList(enabledIds);
+		const enabledCount = enabledCountOf(allowedList, roster.map((row) => row.id));
 		const contextWindow = await providerStore.contextWindow().catch(() => null);
-		const allowed = resolveAllowedList(enabledIds);
-		const allowSet = new Set(enabledIds);
-		const enabledCount = allowed === "all" ? roster.length : allowed === "list" ? roster.filter((row) => allowSet.has(row.id)).length : 0;
 		return {
 			enabled,
 			source,
@@ -3839,7 +4783,7 @@ async function buildSnapshotBody(wiring) {
 			error: typeof publisher.state.error === "string" ? publisher.state.error : null,
 			modelCount: roster.length,
 			enabledCount,
-			allowed,
+			allowed: allowedList.mode,
 			enabledIds,
 			contextWindow,
 			roster
@@ -3848,19 +4792,26 @@ 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"
 		};
 	})());
+	if (!provider.ok) shapeWarnings.push(`provider source failed (${provider.code}): ${provider.error}`);
+	if (!draw.ok) shapeWarnings.push(`draw source failed (${draw.code}): ${draw.error}`);
 	const usedLocal = daily.ok ? daily.value.calls : null;
 	return {
 		ok: true,
@@ -3900,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: {
@@ -3909,7 +4862,7 @@ async function buildSnapshotBody(wiring) {
 			sample: modelIds.slice(0, 20),
 			error: models.ok ? null : models.error
 		},
-		provider: provider.ok ? provider.value : providerDegraded(provider.error),
+		...provider.ok ? { provider: provider.value } : {},
 		...draw.ok ? { draw: draw.value } : {},
 		shapeWarnings,
 		quotaError: null
@@ -3958,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);
 		}
@@ -4008,7 +4961,7 @@ function refuseMethod(response) {
 * 日志或响应）。redactSecrets 幂等，双重应用无害。
 */
 function redactedError(error) {
-	const text = redactSecrets$1(errMsg(error));
+	const text = redactSecrets(errMsg(error));
 	return text.trim() === "" ? "request failed" : text;
 }
 /**
@@ -4314,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 : [];
 }
 /**
@@ -4342,18 +5295,12 @@ async function readEnabledIds(store, published) {
 	return resolveEnabledIds(await optional(store.enabledIds?.(), null), published);
 }
 /**
-* `allowed` 的分类：委托给 `llm-models.ts` 的单一口径
-* {@link resolveAllowedList}（fix D：快照与 provider 路由以前各写一套分类，会漂移）。
-*
-* 旧版 `allowedOf` 只认「恰好哨兵」为 `"none"`，`["__hide_all__","other"]` 会被错判成
-* `"list"`；统一到 `resolveAllowedList` 后，含哨兵即 `"none"`，与 `filterByEnabled` /
-* `isModelEnabled` 口径一致。
-* @param {string[]} enabledIds - 允许清单。
-* @returns {"all"|"none"|"list"}
+* `allowed` 的分类与 `enabledCount` 的计数：都从 `shared/allow-list.ts` 的
+* {@link parseAllowedList} 联合上取（fix D：快照与 provider 路由以前各写一套
+* 分类，会漂移；旧版 `allowedOf` 只认「恰好哨兵」为 `"none"`，
+* `["__hide_all__","other"]` 会被错判成 `"list"`——统一到联合后，含哨兵即
+* `"none"`，与 `filterByEnabled` / `isModelEnabled` 同一份解释）。
 */
-function allowedOf(enabledIds) {
-	return resolveAllowedList(enabledIds);
-}
 /**
 * 注册 provider 路由（三条路径）。wiring 子集：settings / providerStore /
 * publisher / inference / logger。
@@ -4362,22 +5309,34 @@ function allowedOf(enabledIds) {
 * @returns {Function} 依次调用三个 `off()` 的注销回调。
 */
 function registerProviderRoute(ctx, wiring) {
-	const { settings, providerStore, publisher, inference, logger } = wiring;
+	const { settings, providerStore, publisher, reconcile, inference, logger } = 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 allowed = allowedOf(enabledIds);
+		const allowedList = parseAllowedList(enabledIds);
 		const modelCount = roster.length;
-		const allowSet = new Set(enabledIds);
 		return {
 			ok: true,
 			enabled: resolveSwitchEnabled(panelSwitch, settings.registerProvider),
@@ -4386,11 +5345,12 @@ function registerProviderRoute(ctx, wiring) {
 			registered: publisher.state.registered === true,
 			error: typeof publisher.state.error === "string" ? publisher.state.error : null,
 			modelCount,
-			enabledCount: allowed === "all" ? modelCount : allowed === "none" ? 0 : roster.filter((row) => allowSet.has(row.id)).length,
-			allowed,
+			enabledCount: enabledCountOf(allowedList, roster.map((row) => row.id)),
+			allowed: allowedList.mode,
 			enabledIds,
 			contextWindow,
 			roster,
+			...catalogError !== null ? { catalogError } : {},
 			...extra
 		};
 	};
@@ -4401,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") {
@@ -4419,13 +5383,12 @@ function registerProviderRoute(ctx, wiring) {
 			}
 			try {
 				await providerStore.save(body.enabled);
-				const entries = await readEntries$1(inference, providerStore);
-				await publisher.publish(entries, await readEnabledIds(providerStore, publisher.state.enabledIds), []);
+				await reconcile();
 			} catch (error) {
 				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({
@@ -4448,13 +5411,12 @@ function registerProviderRoute(ctx, wiring) {
 			const ids = body.enabledIds.filter((id) => typeof id === "string" && id !== "");
 			try {
 				await providerStore.saveEnabledIds?.(ids);
-				const entries = await readEntries$1(inference, providerStore);
-				await publisher.publish(entries, ids, []);
+				await reconcile();
 			} catch (error) {
 				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({
@@ -4476,13 +5438,12 @@ function registerProviderRoute(ctx, wiring) {
 			}
 			try {
 				await providerStore.saveContextWindow?.(body.contextWindow);
-				const entries = await readEntries$1(inference, providerStore);
-				await publisher.publish(entries, await readEnabledIds(providerStore, publisher.state.enabledIds), []);
+				await reconcile();
 			} catch (error) {
 				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({
@@ -4500,13 +5461,12 @@ function registerProviderRoute(ctx, wiring) {
 			try {
 				await providerStore.forget();
 				await providerStore.saveEnabledIds?.([]);
-				const entries = await readEntries$1(inference, providerStore);
-				await publisher.publish(entries, [], []);
+				await reconcile();
 			} catch (error) {
 				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 () => {
@@ -4570,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(),
 			/**
 			* 开关的保存**不会**改变本次挂载的工具。
@@ -4633,20 +5597,8 @@ function registerDrawRoute(ctx, wiring) {
 				return;
 			}
 			try {
-				if (hasEnabled) {
-					const refusal = await drawStore.saveEnabled(body.enabled);
-					if (refusal !== null) {
-						respondError(response, new Error(refusal));
-						return;
-					}
-				}
-				if (body.modelId !== void 0) {
-					const refusal = await drawStore.saveModelId(body.modelId);
-					if (refusal !== null) {
-						respondError(response, new Error(refusal));
-						return;
-					}
-				}
+				if (hasEnabled) await drawStore.saveEnabled(body.enabled);
+				if (body.modelId !== void 0) await drawStore.saveModelId(body.modelId);
 			} catch (error) {
 				respondError(response, error);
 				return;
@@ -4667,11 +5619,7 @@ function registerDrawRoute(ctx, wiring) {
 				error: "ignored"
 			}));
 			try {
-				const refusal = await drawStore.reset();
-				if (refusal !== null) {
-					respondError(response, new Error(refusal));
-					return;
-				}
+				await drawStore.reset();
 			} catch (error) {
 				respondError(response, error);
 				return;
@@ -4688,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
 /**
@@ -4704,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)
 	];
 }
 
@@ -4752,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
 	});
@@ -4770,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(),
@@ -4786,49 +5828,13 @@ function apply(ctx, config = {}, deps = {}) {
 		...deps.loadAdapterModule ? { loadAdapterModule: deps.loadAdapterModule } : {},
 		logger: ctx.logger
 	});
-	/**
-	* 当前允许清单：落盘优先，读不到回退内存最近一次 publish 的清单。
-	*
-	* 判据与另外两个消费者（`snapshot-aggregate.ts` 的面板块、`routes/provider.ts`
-	* 的 GET）**共用** {@link resolveEnabledIds}——空清单是「不过滤，提供全部模型」，
-	* 那是 provider-store 的契约，不是「没有答案」。本函数曾经自己写成
-	* `stored.length > 0` 才算数，于是**可读的空清单**（操作者按 versionNote 的建议
-	* 删掉 provider.json，或清单被保存为空）会让面板说 all、轮询却继续按内存里的旧
-	* 清单注册：面板与 Host 对「正在提供什么」各说一套。只有读**抛错**（`.catch`
-	* → null）才回退内存。
-	* @returns {Promise<string[]>}
-	*/
-	const currentEnabledIds = async () => resolveEnabledIds(await providerStore.enabledIds().catch(() => null), publisher.state.enabledIds);
-	/**
-	* 一次目录轮询：拉目录，再 publish 当前 offer。
-	*
-	* **窗口覆盖必须参与**：catalogSignature 含窗口值，轮询若用未打标条目 publish，
-	* 用户保存覆盖后的每次轮询都会因「签名不同」把注册摘下重挂（覆盖每 pollSeconds
-	* 静默回退一次、适配器每轮重建）。所以 fetch **前**先读落盘覆盖传给 fetchModels，
-	* 与 `currentEnabledIds` 同一模式。
-	*
-	* fetch **后**再读一次：目录拉取可能耗时数百毫秒，期间用户可能保存了新覆盖——
-	* 保存路由已经用新值 publish 过，此时用旧标条目 publish 反而把注册**倒退**一个
-	* 周期；这种窗口内跳过本轮即可（下一轮轮询自然带新值）。清单沿用 fetch 后读的
-	* 老顺序（捕获 fetch 期间的编辑），两条时序理由同源。
-	* @returns {Promise<void>}
-	*/
-	const runPoll = async () => {
-		const contextWindow = await providerStore.contextWindow().catch(() => null);
-		let catalog = null;
-		try {
-			catalog = await inference.fetchModels(contextWindow);
-		} catch (error) {
-			ctx.logger?.warn?.(`${name}: catalog fetch failed (${redactSecrets$1(errMsg(error))}) — the next poll retries; the panel keeps its degraded models block`);
-			return;
-		}
-		if (await providerStore.contextWindow().catch(() => null) !== contextWindow) return;
-		try {
-			await publisher.publish(catalog.entries, await currentEnabledIds(), []);
-		} catch (error) {
-			ctx.logger?.warn?.(`${name}: publish failed (${redactSecrets$1(errMsg(error))}) — the catalog is current, only the provider registration did not land`);
-		}
-	};
+	const { reconcile } = createProviderReconciler({
+		settings,
+		providerStore,
+		inference,
+		publisher,
+		logger: ctx.logger
+	});
 	const wiring = {
 		settings,
 		configError,
@@ -4837,15 +5843,17 @@ function apply(ctx, config = {}, deps = {}) {
 		inference,
 		providerStore,
 		drawStore,
+		usagePrefsStore,
 		publisher,
+		reconcile,
 		logger: ctx.logger
 	};
 	const offs = registerRoutes(ctx, wiring);
 	ctx.effect(() => {
-		runPoll();
+		reconcile();
 		registerDrawTool(ctx, wiring, deps);
 		const timer = setInterval(() => {
-			runPoll();
+			reconcile();
 		}, settings.pollSeconds * 1e3);
 		return () => {
 			clearInterval(timer);
@@ -4855,7 +5863,7 @@ function apply(ctx, config = {}, deps = {}) {
 			for (const off of offs) try {
 				off?.();
 			} catch (error) {
-				ctx.logger?.warn?.(`${name}: route unregister failed: ${redactSecrets$1(errMsg(error))}`);
+				ctx.logger?.warn?.(`${name}: route unregister failed: ${redactSecrets(errMsg(error))}`);
 			}
 		};
 	}, `${name}: routes`);