dsh-connect-modelscope-token-plan 0.3.0 → 0.4.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 obj, D as str, E as redactSecrets, O as verbatim, S as errMsg, T as pluginError, a as resolveSettings, c as LLM_PROVIDER_ID, d as isVisionModel, f as normalizeEntry, g as parseAllowedList, h as enabledCountOf, i as name, m as textToImageModelIds, n as inject, p as rosterWithAvailability, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as imageGenModelIds, v as hasHardQuotaWordingIn, w as optional, x as degrade, y as looksLikeRateLimit } from "./host-config.js";
+import { 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），空白值视为没输入。
@@ -146,36 +184,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 +205,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 +220,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 +249,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 +627,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 +743,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 +767,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 +828,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 日期）与平台文案里写明的等待时长。
@@ -859,8 +993,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 +1016,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,23 +1051,19 @@ 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;
-	};
+	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);
+	});
 	/** 修剪：只留最近 trendDays 个天桶（按 dateKey 排序，今天不删）。 */
 	const pruneDays = (payload, todayKey) => {
 		const keep = new Set(Object.keys(payload.days).sort().slice(-Math.max(1, trendDays)));
@@ -1372,7 +1504,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);
 		}
@@ -1467,7 +1599,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("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:[...]})");
@@ -1536,7 +1668,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 +1710,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();
@@ -1795,28 +1927,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 +1985,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 +1998,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();
@@ -1918,7 +2044,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 +2064,6 @@ function createFileProviderStore(options = {}) {
 			});
 			return refusal;
 		});
-		writeChain = run.catch(() => null);
-		return run;
 	};
 	return {
 		/**
@@ -1994,7 +2118,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 +2199,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
 */
@@ -2083,9 +2232,19 @@ const EMPTY_PAYLOAD = {
 	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 +2282,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 +2326,84 @@ function createFileDrawStore(options = {}) {
 	* 读当前 payload。
 	* @returns {Promise<DrawPayload>}
 	*/
-	const current = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD;
 	/**
-	* 写一份补丁并落盘。
-	* @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
 			});
@@ -2233,6 +2440,13 @@ function createFileDrawStore(options = {}) {
 *    空串，没有顶层 `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
 */
 /**
@@ -2255,8 +2469,19 @@ const DRAW_TIMEOUT_MS = 9e5;
 * 详见 docs/SPIKE-image-gen.md §坑 4（含撤回记录）。
 */
 const DRAW_POLL_INTERVAL_MS = 15e3;
-/** 轮询的总截止时间；与 `DRAW_TIMEOUT_MS` 同量级但独立可调（诊断时可放宽）。 */
-const DRAW_POLL_DEADLINE_MS = DRAW_TIMEOUT_MS;
+/**
+* 一次**工具调用**里愿意等的时间（毫秒）。
+*
+* 出图工具是给 agent 用的，一次调用阻塞 = 一整轮对话被占住。15 分钟的总预算
+* （{@link DRAW_TIMEOUT_MS}）是「这张图值不值得继续等」的上限，不是「一次调用
+* 该不该堵住 agent」的上限——两者同一个数，就是把上游排队的代价转嫁成对话的
+* 停顿。
+*
+* 取 90s：实测耗时 61s–537s 大幅波动，90s 能一次拿完最快那一档（61s），而
+* 更慢的本来就必须分段查（见 `draw-runtime.ts` 的两段式工具）。再往上加只是
+* 把「等得久」换成「卡得久」，并不改变「慢的图要分几次查」这个事实。
+*/
+const DRAW_WAIT_BUDGET_MS = 9e4;
 /**
 * 轮询必须携带的头名与取值。
 *
@@ -2361,17 +2586,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 +2663,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 +2696,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 +2761,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` 就结束。魔搭是
@@ -2559,28 +2839,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,12 +2886,40 @@ 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 }) {
+	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 分钟间大幅波动，与请求本身无关。稍后可重试；注意超时后原任务的结果不保证还能取回` }));
+		if (Date.now() >= deadline) return {
+			kind: "pending",
+			polls
+		};
 		await sleep(interval);
 		polls++;
 		let polled;
@@ -2639,29 +2935,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
 		};
 	}
@@ -2711,30 +3015,115 @@ function drawModelIds(entries) {
 	return imageGenModelIds(entries);
 }
 /**
-* 装配 agent 工具定义。
+* 装配 agent 工具定义——**两段式**，一次调用不再阻塞整轮对话。
+*
+* ## 为什么是两段式
+*
+* 上游出图要排队，实测 61s–537s（免费池）。旧形状是「一次调用 await 到终态」，
+* 于是 `drawTimeoutMs`（15 分钟）既是「这张图值不值得等」的上限，也成了「一轮
+* 对话被卡多久」的上限——把上游排队的代价直接转嫁成对话停顿。
+*
+* 现在一次调用只做两件事之一：
+*   - **不带 `jobId`** → 提交任务，然后只在 `waitMs`（默认 {@link DRAW_WAIT_BUDGET_MS}）
+*     内等；等到就返回 `done`，没等到就返回 `pending` + `jobId`；
+*   - **带 `jobId`** → 只查那个任务，同样最多等 `waitMs`。
+*
+* `drawTimeoutMs` 因此回到它本来的语义：**从提交算起的总放弃线**（跨调用累计），
+* 越过它才报「放弃」。
 *
-* 工具只做「参数归一 → 跑一次 → 组装结果文本」，所有判定都委托给 `draw.ts` 的纯函数。
+* ## 两个刻意的判定
+*
+*   - `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");
+	/**
+	* 等一个作业，把 {@link awaitDrawTask} 的三种结局翻译成工具结果或错误。
+	*
+	* 两段共用这一段——「刚提交的」与「续查的」在等待这件事上没有区别，唯一的区别
+	* 是作业表里那条记录从哪来。
+	* @param {string} apiKey - 访问令牌。
+	* @param {DrawJob} job - 作业（含提交时刻与累计轮询数）。
+	* @param {string[]} available - 目录里的出图模型（续查时为空，不必再拉目录）。
+	* @returns {Promise<DrawToolResult>} 工具结果。
+	* @throws {Error} 真失败（上游 FAILED / 轮询 HTTP 失败）或越过总放弃线。
+	*/
+	const waitAndReport = async (apiKey, job, available) => {
+		const awaited = await awaitDrawTask({
+			fetchImpl,
+			apiBase,
+			apiKey,
+			taskId: job.taskId,
+			waitMs,
+			pollIntervalMs
+		});
+		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 an array of URLs for multi-image editing. Omit `model` to use the catalogue's image model. TWO-PHASE: upstream generation queues, so latency varies from ~1 minute to 15+ minutes. Call without `jobId` to submit and wait briefly; if the result is `status: pending`, call again with the returned `jobId` to keep polling. A pending result is NOT a failure — the image is still being generated. Available image model ids are reported in the result.",
 		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 +3160,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 +3173,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");
+			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 +3218,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 +3229,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;
@@ -2993,9 +3391,13 @@ 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` 惰性注入。
+*
+* **本文件目前没有测试覆盖**——`registerDrawTool` 在 `test/` 里零引用
+* （docs/ROADMAP.md Backlog 记着这条缺口）。但**这不是「不能」**：同一处境的
+* `llm-adapter.ts` / `draw-runtime.ts` 已经用 `test/helpers/peer-stub-loader.mjs`
+* 证明这类模块能在离线套件里原样加载执行。此前的措辞把 `llm-adapter.ts` 当作
+* 「同样无法导入」的例证拉来作证，那条类比在补上那个 loader 之后已经失效。
 *
 * @module dsh-connect-modelscope-token-plan/draw-register
 */
@@ -3046,7 +3448,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 +3470,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 +3668,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 +3774,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 +3853,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 +3878,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 +3981,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 +4022,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 +4045,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,
@@ -3608,31 +4070,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 +4146,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 开关、
@@ -3713,6 +4235,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 > 100) break;
+			}
+		});
+	};
+	return { reconcile };
+}
+
 //#endregion
 //#region src/host/routes/paths.ts
 /**
@@ -3767,30 +4410,11 @@ 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;
@@ -3820,6 +4444,8 @@ 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 provider = await soft((async () => {
 		const panel = await providerStore.enabled().catch(() => null);
 		const enabled = resolveSwitchEnabled(panel, settings.registerProvider);
@@ -3827,10 +4453,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 +4464,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
@@ -3861,6 +4486,8 @@ async function buildSnapshotBody(wiring) {
 			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,
@@ -3909,7 +4536,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
@@ -4008,7 +4635,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;
 }
 /**
@@ -4342,18 +4969,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,7 +4983,7 @@ 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 共用，所以两个方向不可能对「当前
 	* 状态是什么」说两套话。
@@ -4375,9 +4996,8 @@ function registerProviderRoute(ctx, wiring) {
 		const contextWindow = await optional(providerStore.contextWindow?.(), null);
 		const entries = await readEntries$1(inference, providerStore);
 		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,8 +5006,8 @@ 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,
@@ -4419,8 +5039,7 @@ 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;
@@ -4448,8 +5067,7 @@ 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;
@@ -4476,8 +5094,7 @@ 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;
@@ -4500,8 +5117,7 @@ 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;
@@ -4633,20 +5249,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 +5271,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;
@@ -4786,49 +5386,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,
@@ -4838,14 +5402,15 @@ function apply(ctx, config = {}, deps = {}) {
 		providerStore,
 		drawStore,
 		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 +5420,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`);