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

package/lib/index.js

@@ -1,6 +1,6 @@
-import { C as redactSecrets, S as pluginError, T as verbatim, a as resolveSettings, b as obj, c as LLM_PROVIDER_ID, d as normalizeEntry, f as resolveAllowedList, g as looksLikeRateLimit, h as hasHardQuotaWordingIn, i as name, n as inject, p as rosterWithAvailability, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as isVisionModel, v as degrade, w as str, x as optional, y as errMsg } from "./host-config-C4bWNPWU.js";
-import { join } from "node:path";
-import { mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+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";
 
@@ -64,14 +64,70 @@ function isPlausibleToken(value) {
 * @param {object|Function|null} [options.credentials] - `ctx.credentials` 服务
 *   或其 resolver；**每次使用时解析**（服务可能在本插件挂载之后才注册，
 *   一次性查找会把错误的 "ephemeral" 断言冻进后续每个轮询）。
-* @param {object} [options.env] - 环境源；默认 `process.env`。
+* @param {object} [options.env] - 环境源；**默认 `process.env`**。
+*   测试经 `apply()` 的 `deps.env` 注入 `{}` 以隔离宿主环境——本文件时不能假设
+*   「没有传就是要用真环境」以外的语义，但调用方可以（详见 types.ts 的 env 缝）。
+*
+*   `| undefined` 不是冗余：`tsconfig` 开了 `exactOptionalPropertyTypes`，
+*   「可选」不允许被显式赋值为 `undefined`，而 `apply()` 是原样转发 `deps.env`
+*   （产品侧不传时它就是 `undefined`）。不写这一半，转发点编译不过。
 */
 function createTokenStore({ credentials = null, env = process.env } = {}) {
 	/** 无凭据服务的 Host 的内存兜底。 */
 	const memory = /* @__PURE__ */ new Map();
+	/**
+	* 最后一次零额度探针的结论（`TokenStatus.valid` / `checkedAt` 的唯一生产者）。
+	*
+	* 只活在本进程：重启即回到「未检查过」，那是诚实答案——`valid: null` 的语义本来
+	* 就是「没检查过」，不是「检查过但没结论」。
+	*
+	* **只在令牌换手时清**（`save` / `forget`）：上一次的结论只对**那一把**令牌成立。
+	* 换令牌后留着旧结论，等于让一个关于别的值的判断继续替新令牌说话——正是
+	* `ephemeral` 那条修正反对的「不是判出来的、是碰巧对的」。env 在 DSH 启动时读
+	* 一次，进程内不会换手，所以这两个入口是全部。
+	*/
+	let lastCheck = null;
 	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），空白值视为没输入。
@@ -95,6 +151,7 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 				await service.set(TOKEN_REF, value);
 				memory.set(TOKEN_REF, value);
 			} else memory.set(TOKEN_REF, value);
+			lastCheck = null;
 		},
 		/**
 		* 忘掉面板保存的令牌。env 回退**不动**——清面板引用不能删操作者的 .env。
@@ -107,46 +164,39 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		*/
 		async forget() {
 			memory.delete(TOKEN_REF);
+			lastCheck = null;
 			const service = resolveService();
 			if (service !== null && typeof service.unset === "function") await service.unset(TOKEN_REF);
 		},
 		/**
-		* 解析当前令牌与来源。返回类型显式注解：这是快照 TokenStatus.source
-		* 联合类型的上游，靠推断会把字面量联合拓宽成 string。
+		* 记录一次**零额度探针**的结论（probe 路由是唯一调用方）。
+		*
+		* 只接已经判出来的结论：`true`（200/400，令牌好）或 `false`（401/403，令牌坏）。
+		* 429 / 上游错误 / 配置错误**不调用**——那些回答的是「上游现在忙不忙」或
+		* 「这次请求成没成」，不是「这把令牌好不好」，把它们记进 `valid` 就是把限频
+		* 说成令牌坏（正是 429 分诊那条修正反对的误判）。不调用即留着上一次的结论，
+		* 那是已知的最好答案。
+		*/
+		noteValidity(valid) {
+			lastCheck = {
+				valid,
+				checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+		},
+		/**
+		* 解析当前令牌与来源。
 		* @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();
 		},
 		/**
 		* 无秘密的状态描述（快照与面板消费）。
-		* `valid` 恒为 null：本模块不做有效性断言（零额度探针在 probe 路由，
-		* 语义已于 2026-10-04 真机回填——判定 401/403 = 令牌坏、200/400 = 令牌好；
-		* SPIKE.md §结论 5）。
+		*
+		* `valid` / `checkedAt` 来自 `noteValidity`（零额度探针的结论），**本模块自己
+		* 不做有效性断言**——判定规则在 probe 路由（401/403 = 令牌坏、200/400 = 令牌好，
+		* 2026-10-04 真机回填；SPIKE.md §结论 5）。没探过就是 `null`，那不是「无效」，
+		* 是「没检查过」。
 		*
 		* `ephemeral` 答的是「**手里这个值**重启会不会丢」，不是「有没有凭据服务」
 		* ——wire 的定义是前者。曾经只按「服务缺席」置位，于是两种都说谎：没有服务
@@ -155,12 +205,12 @@ 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,
-				valid: null,
-				checkedAt: null,
+				valid: lastCheck === null ? null : lastCheck.valid,
+				checkedAt: lastCheck === null ? null : lastCheck.checkedAt,
 				ephemeral: source === "memory"
 			};
 		}
@@ -170,16 +220,16 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 //#endregion
 //#region src/host/state-store.ts
 /**
-* 状态文件公共原语 —— 把本插件的各 store（usage-store）从
-* 各自手写的同一段"版本载荷 + temp 文件 + rename 原子 + 0600 + 损坏即忽略"
-* 收敛到这里（家规：peer-free、离线可测）。。
+* 状态文件公共原语。**TL;DR**：本文件只做四件事——`dshHome`/`stateDir`（定位
+* 状态目录）、`profileSegment`（按 profile 分段路径）、{@link createStateReadCache}
+* （统一读缓存）、以及写侧三件套（{@link createStateWriteQueue} 写串行化 /
+* {@link guardStateWrite} ADR-006 写守卫 / {@link stateVersionNote} 读侧版本说明）。
+* 其余一切遵守下方「行为约定」。
 *
-* 第二步收敛的是**读缓存**：provider / draw 早有 1s TTL，而 catalog 完全没有
-* （进程内永不失效）——同一个「两个进程共享一个 state 目录」的问题修了两个、
-* 漏了第三个。现在统一走 {@link createStateReadCache}，一个 TTL 三个调用方。
-*
-* peer-free 与四个 store 同纪律：不 import 任何 Host peer，纯 `node:fs`，
-* 离线可测（store.test.mjs 直接注入 dir 构造即可）。
+* 把本插件各 store（usage-store / provider / draw）各自手写的同一段
+* "版本载荷 + temp 文件 + rename 原子 + 0600 + 损坏即忽略" 收敛到这里。
+* 家规：peer-free（不 import 任何 Host peer，纯 `node:fs`）、离线可测
+* （store.test.mjs 直接注入 dir 构造即可）。
 *
 * 行为约定（与本插件 store 的约定逐一对齐）：
 *   - 目录：`$DSH_HOME/state/<name>`——与 Host 自己的目录并列，而不是在
@@ -187,29 +237,39 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 *   - 写：临时文件（0600，owner-only）→ `rename` 原子落位。**失败抛错**，
 *     是否吞错是各 store 的语义（usage-store 面对只读 Home 选择吞、
 *     provider 面板开关交给调用方的错误路径），原语不做决定。
-*   - 临时名：进程 + 时间戳 + 随机 UUID 后缀。固定临时名会让两个 Host 进程的
-*     写落到同一路径、互相 `rename` 掉对方写了一半的文件；同一进程同一毫秒的
-*     两次异步写也会撞名（`writeFile` 截断覆盖后一次 `rename` 静默丢写），
-*     随机后缀让每个 temp 路径唯一，`rename` 原子性借此成立（见 `temporaryOf`）。
-*     此前的写法曾只有进程 + 时间戳，同毫秒并发写会静默丢一条。
+*   - 临时名：进程 + 时间戳 + 随机 UUID 后缀。随机后缀让每个 temp 路径唯一，
+*     `rename` 原子性借此成立（见 `temporaryOf`）。
 *   - 读：缺失、不可读、非 JSON 一律返回 `null`——"损坏即忽略"的方向。是否
 *     缓存、缓存多久由 {@link createStateReadCache} 决定，不是每个 store 各自的
 *     即兴实现。
 *
+* ## 演变记录（历史，非契约）
+* 1. 第一步收敛的是上述「版本载荷 + 临时文件 + 原子落位」；临时名此前只有
+*    进程 + 时间戳，同毫秒并发写会静默丢一条，故加随机后缀。
+* 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
 */
 /**
-* The DSH home: `$DSH_HOME` when the operator exported one, else `~/.dsh`.
-* @returns {string} the home directory.
+* DSH 主目录：操作者导出了 `DSH_HOME` 就用它，否则回落到 `~/.dsh`。
+* @returns {string} 主目录。
 */
 function dshHome() {
 	return str(process.env.DSH_HOME, join(homedir(), ".dsh"));
 }
 /**
-* Where this plugin keeps state: `$DSH_HOME/state/<name>`.
-* @param {string} name - the plugin's own state directory name
-*   (`host-config.ts`'s `name`).
-* @returns {string} the directory.
+* 本插件存放状态的位置：`$DSH_HOME/state/<name>`。
+* @param {string} name - 插件自己的状态目录名（即 `host-config.ts` 的 `name`）。
+* @returns {string} 目录路径。
 */
 function stateDir(name) {
 	return join(dshHome(), "state", name);
@@ -229,9 +289,9 @@ function stateDir(name) {
 const PROFILE_SEGMENT_MAX = 64;
 const PROFILE_SEGMENT_RE = /^(?!\.)[A-Za-z0-9._-]+$/;
 /**
-* Is this string safe to use as ONE path segment?
-* @param {unknown} value - candidate profile name.
-* @returns {boolean} true when it survives {@link PROFILE_SEGMENT_RE}.
+* 该字符串能否安全地作为**一个**路径段使用？
+* @param {unknown} value - 候选 profile 名。
+* @returns {boolean} 通过 {@link PROFILE_SEGMENT_RE} 即为 true。
 */
 function isProfileSegment(value) {
 	if (typeof value !== "string") return false;
@@ -263,8 +323,8 @@ function isProfileSegment(value) {
 *
 * 取到 = 调用方据此分段；取不到 = **退回当前的全局路径**，行为零漂移。
 *
-* @param {object} [ctx] - the Cordis context the Host handed `apply()`.
-* @returns {string|null} the profile name, or `null` when unavailable/unsafe.
+* @param {object} [ctx] - Host 交给 `apply()` 的 Cordis context。
+* @returns {string|null} profile 名，取不到或不安全时为 `null`。
 */
 function profileSegment(ctx) {
 	if (ctx === null || typeof ctx !== "object") return null;
@@ -510,22 +570,46 @@ async function readStateJson(file) {
 	}
 }
 /**
-* Read the persisted `version` field of one state file, or `null` when it is
-* absent, unreadable, non-JSON, or carries no numeric `version`.
+* Read the persisted `version` field of one state file.
 *
 * This is the ADR-006 write-side guard's probe: a writer must know what it is
-* about to overwrite. "No version" is the same as "no record" (nothing to
-* protect), while a NUMERIC version this build does not recognise means the
-* file was written by a NEWER build and must not be clobbered.
+* about to overwrite. Three outcomes, and the difference between the first two
+* is load-bearing:
+*
+*   - `null` — ABSENT (ENOENT), non-JSON, or carrying no numeric `version`.
+*     Nothing here the guard could protect, so a write belongs: a corrupt file
+*     must stay replaceable, or an operator would be stuck with it forever.
+*   - a number — the version on disk. One this build does not recognise was
+*     written by a NEWER build and must not be clobbered.
+*   - **throws** — the path EXISTS but could not be read (EACCES/EBUSY/EIO, or a
+*     directory sitting at the path). The guard must read that as "there is
+*     something here and I cannot see it", never as "nothing stored": collapsing
+*     it into `null` made the anti-clobber guard fail OPEN, so the very
+*     downgrade it exists to prevent came through that seam.
 *
 * Kept apart from `readStateJson` on purpose: the guard needs the version even
-* when the rest of the payload is unparseable, and it must not depend on any
-* store's parse semantics.
+* when the rest of the payload is unparseable, it must not depend on any store's
+* parse semantics, and it must NOT inherit the read path's deliberate "anything
+* unrecognised reads as not set" permissiveness — that permissiveness is right
+* for a reader and wrong for a writer.
 * @param {string} file - the state file path.
-* @returns {Promise<number|null>} the persisted version, or `null`.
+* @returns {Promise<number|null>} the persisted version, or `null` when absent/unusable.
+* @throws when the path exists but cannot be read — callers must refuse to write.
 */
 async function readStateVersion(file) {
-	const raw = await readStateJson(file);
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch (error) {
+		if (error?.code === "ENOENT") return null;
+		throw error;
+	}
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return null;
+	}
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
 	const version = raw.version;
 	return typeof version === "number" ? version : null;
@@ -543,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 文案**做的保守二分——
@@ -556,7 +742,10 @@ function isKnownStateVersion(version, known) {
 *
 * @module dsh-connect-modelscope-token-plan/codes
 */
-/** 面板按它分流的稳定码表。 */
+/**
+* 面板按它分流的稳定码表 —— Client 的 `GUIDANCE_BY_CODE` 以这份表的键为契约
+* （且以 `CodeValue` 为**类型**契约：缺键是编译错误，不再只靠测试红）。
+*/
 const CODE = Object.freeze({
 	CONFIG_ERROR: "config_error",
 	NETWORK_ERROR: "network_error",
@@ -573,19 +762,41 @@ const CODE = Object.freeze({
 	* 「每个键必须在 CODE 里」），最需要人看的内部错误反而没有引导文案。
 	* 正式收进码表，两端从此同一份真源。
 	*/
-	INTERNAL_ERROR: "internal_error"
+	INTERNAL_ERROR: "internal_error",
+	/**
+	* Client 自产码：Host 响应无法解读成快照（非 JSON / 缺 ok 字段）时，
+	* 面板用它走引导文案，而不是把裸英文串（"unexpected payload"）上屏。
+	*
+	* 本表是 `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 状态归类成稳定码。
 *
 * 401/403 → AUTH_ERROR（换令牌能修，绝不自动重试——魔搭没有锁号问题，
 * 但重试一个坏令牌只会刷屏）；429 由调用方先走 {@link classifyRateLimit}
-* 分诊，这里只兜底；5xx → UPSTREAM_ERROR；其余 → NETWORK_ERROR。
+* 分诊，这里只兜底；其余 4xx/5xx → UPSTREAM_ERROR；低于 400 → NETWORK_ERROR。
 */
 function classifyStatus(status) {
 	if (status === 401 || status === 403) return CODE.AUTH_ERROR;
 	if (status === 429) return CODE.RATE_LIMITED;
-	if (status >= 500) return CODE.UPSTREAM_ERROR;
 	if (status >= 400) return CODE.UPSTREAM_ERROR;
 	return CODE.NETWORK_ERROR;
 }
@@ -617,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 日期）与平台文案里写明的等待时长。
@@ -684,6 +891,19 @@ function parseRetryAfterMs(headers, message) {
 function localDateKey(now) {
 	return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
 }
+/**
+* 路径在不在（任何 fs 错误都读作「不在」——存在性问的是能不能 `ls` 到它。
+* EACCES 让 `stat` 失败时，真相其实是「在，只是看不见」，而对下面的判据来说
+* 那同样不能被当成「没有记录」）。
+*/
+async function pathExists(file) {
+	try {
+		await stat(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
 const STATE_VERSION = 1;
 const KNOWN_VERSIONS = [STATE_VERSION];
 /** 解析并校验磁盘载荷；形状不对读作 null（损坏即忽略），并标记异常。 */
@@ -773,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();
 	/**
 	* 磁盘版本闸 —— 读路径与写路径**各自**调用，不共享副作用。
 	*
@@ -790,7 +1012,16 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 	* @returns `true` = 磁盘版本比本构建新（写必须拒绝）；`false` = 可以写。
 	*/
 	const diskVersionBlocksWrites = async () => {
-		const onDisk = await readStateVersion(file);
+		let onDisk;
+		try {
+			onDisk = await readStateVersion(file);
+		} catch (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;
+			return true;
+		}
 		if (onDisk !== null && !isKnownStateVersion(onDisk, KNOWN_VERSIONS)) {
 			const note = `usage-state: on-disk version ${onDisk} is newer than this build knows`;
 			if (!readOnly) logger?.warn?.(`${name}: ${note} — recording disabled to avoid clobbering`);
@@ -820,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 = (loaded ? current : await cache.read() ?? 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)));
@@ -891,16 +1118,47 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 				}, ...payload.events].slice(0, maxEvents);
 			});
 		},
-		/** 今天（本地时区）的账户级计数；没有任何记录时是 0，不是 null。 */
+		/**
+		* 今天（本地时区）的账户级计数。
+		*
+		* 三种答案，三种含义，**不可合并**（wire.ts DailyUsage 的语义基线）：
+		*   - `0` —— 确实一次都没有（没记录，或今天还没有桶）；这是可信的日常值；
+		*   - `null` —— **读不到**：文件在，但本构建看不懂它（损坏 / 形状不对 / 更新
+		*     构建写的版本 / 存在却不可读）。面板渲染「—」；
+		*   - 数字 —— 今日次数。
+		*
+		* 判据是「文件在不在」而不是「载荷读没读出来」：**文件不存在**才是真实的 0
+		* （这台 Host 从未经本插件调用过，不是数据丢失），而**文件在却读成空**代表
+		* 我们失去了那部分信息——把它报成 0 会让操作者以为今天没调用过，真相是他
+		* 不知道。
+		*
+		* 这是 2026-10-16 补上的一块拼图：`routes.test.mjs` 早有一条
+		* 「本地计数读不到 → null，绝不是 0」的断言，但它只能用一个**会抛错的桩**
+		* 造出那条路径（注释原话：「挂载的真实 store 造不出『读的时候抛』」）——
+		* 真实 store 把所有读失败都吞成了空载荷。于是 null 那份语义在 wire.ts、
+		* `cards.ts`、`snapshot-aggregate.ts` 里写了三遍，却从未在本机真的产出过。
+		*
+		* @returns {{dateKey: string, calls: number|null, tokens: number|null}}
+		*/
 		async daily() {
-			const day = (await cache.read())?.days[localDateKey(now())] ?? null;
+			const payload = await cache.read();
+			const dateKey = localDateKey(now());
+			if (payload === null) {
+				const stored = await pathExists(file);
+				return {
+					dateKey,
+					calls: stored ? null : 0,
+					tokens: stored ? null : 0
+				};
+			}
+			const day = payload.days[dateKey] ?? null;
 			return day === null ? {
-				dateKey: localDateKey(now()),
+				dateKey,
 				calls: 0,
 				tokens: 0
 			} : {
 				...day,
-				dateKey: localDateKey(now())
+				dateKey
 			};
 		},
 		/** 今天的单模型计数（只含有记录的模型，dayCalls/dayTokens 口径，均跨日清零）。 */
@@ -1005,6 +1263,13 @@ const MAX_CACHE_AGE_MS = 36e5;
 * flight's answer would be served to the account that just signed in.
 * Hanging the counters off the map makes every instance over that map share
 * one generation state, so the guard holds no matter how the caller builds it.
+*
+* `seq` is the ONE monotonic source both bumps draw from (see
+* {@link clearCoalescedFetch}): `global` is a high-water mark that only a global
+* clear moves, and `keys` holds one absolute number per individually-cleared
+* key. `keys` is therefore bounded by the number of distinct keys cleared since
+* the last global clear — not swept, because a per-key number must outlive any
+* in-flight flight born under it, while a later global clear wipes them all.
 */
 const GENERATIONS = /* @__PURE__ */ new WeakMap();
 /** The (created-on-demand) generation state belonging to one cache map. */
@@ -1013,6 +1278,7 @@ function generationsOf(cache) {
 	if (state === void 0) {
 		state = {
 			global: 0,
+			seq: 0,
 			keys: /* @__PURE__ */ new Map()
 		};
 		GENERATIONS.set(cache, state);
@@ -1034,14 +1300,15 @@ function generationsOf(cache) {
 */
 function clearCoalescedFetch(cache, inflight, key) {
 	const gens = generationsOf(cache);
+	gens.seq += 1;
 	if (key === void 0) {
-		gens.global += 1;
+		gens.global = gens.seq;
 		cache.clear();
 		inflight.clear();
 		gens.keys.clear();
 		return;
 	}
-	gens.keys.set(key, (gens.keys.get(key) ?? gens.global) + 1);
+	gens.keys.set(key, gens.seq);
 	cache.delete(key);
 	inflight.delete(key);
 }
@@ -1116,6 +1383,66 @@ function createCoalescedFetch(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/context-catalog.ts
+/**
+* 内置上下文窗口策展表——魔搭目录不声明窗口时的第三方真值来源。
+*
+* 魔搭 `/v1/models`（及模型详情端点）只回基础标识字段（id/object/owned_by/
+* created + Tasks 标签），没有窗口字段；未声明窗口的条目会一路落到
+* `FALLBACK_CONTEXT_WINDOW`（128k）。这张表在「用户全局档位」之外补第三级
+* 真值：目录声明 > 用户覆盖 > **策展表** > 兜底。
+*
+* 数据来自 models.dev 聚合（github.com/anomalyco/models.dev，MIT；api.json
+* 构建产物）。魔搭 provider 自身在 api.json 只有 7 个不在当前目录的旧模型，
+* 所以每条真值取的是**同 id 模型在各厂自家 host 下的主流 limit.context**——
+* 跨 host 抄写的开量窗口是模型出厂规格，不是各网关的部署配额，取多数而非
+* 最大值：个别网关把窗口抄大（如 openrouter 抄 1M）不代表魔搭侧真开那么宽。
+*
+* 维护纪律：
+* 1. 只收**当前魔搭目录里真实存在**的 id（2026-10-16 实拉 `/v1/models` 全集
+*    37 个中筛出 19 个）；目录下架的条目应随手删除，表不是历史档案。
+* 2. 每条注明来源 host 与核对日期；有多个数据源时写主流值并留离群说明。
+* 3. 覆盖优先级由 `curatedWindowOf` 的调用方（inference-client 打标）保证：
+*    目录声明过窗口的条目不进打标，策展表永不推翻平台声明。
+* 4. 生图/语音模型（Qwen-Image-Edit、ACE-Step 等）无对话上下文，不收。
+*/
+/** id → 标称上下文窗口（tokens）。键必须与魔搭目录 id 逐字一致。 */
+const CURATED_CONTEXT_WINDOWS = {
+	"deepseek-ai/DeepSeek-V4-Flash-0731": 1048576,
+	"deepseek-ai/DeepSeek-V4-Pro": 1048576,
+	"deepseek-ai/DeepSeek-V4-Pro-0813": 1048576,
+	"deepseek-ai/DeepSeek-V4.1-Flash": 1048576,
+	"meituan-longcat/LongCat-Flash-Lite": 256e3,
+	"MiniMax/MiniMax-M1-80k": 1e6,
+	"MiniMax/MiniMax-M3": 1048576,
+	"nex-agi/Nex-N2.5-mini": 262144,
+	"nex-agi/Nex-N2.5-Pro": 262144,
+	"Qwen/Qwen3.5-122B-A10B": 262144,
+	"Qwen/Qwen3.5-27B": 262144,
+	"Qwen/Qwen3.5-35B-A3B": 262144,
+	"Qwen/Qwen3.5-397B-A17B": 262144,
+	"Qwen/Qwen3.8-27B": 262144,
+	"Qwen/Qwen3.8-Flash-Next": 262144,
+	"stepfun-ai/Step-3.5-Flash": 262144,
+	"stepfun-ai/Step-3.7-Flash": 262144,
+	"ZhipuAI/GLM-4.7-Flash": 2e5,
+	"ZhipuAI/GLM-5.2": 1e6
+};
+/**
+* 查策展窗口：命中返回正数，未命中返回 null（调用方继续走兜底）。
+*
+* 只认逐字 id——不做大小写/前后缀模糊匹配，宁可查不到落兜底，也不把
+* 相近 id 的窗口张冠李戴。值合法性再挡一道（表内只应出现正数）。
+* @param {string} id - 模型 id（魔搭目录原样拼写）。
+* @returns {number|null} 标称窗口，未收录为 null。
+*/
+function curatedWindowOf(id) {
+	if (typeof id !== "string" || id === "") return null;
+	const value = CURATED_CONTEXT_WINDOWS[id];
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+
 //#endregion
 //#region src/host/inference-client.ts
 /**
@@ -1245,10 +1572,29 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 		* cacheSeconds。返回归一后的目录条目（entries，M4 用来建 descriptor）与
 		* 派生的 id 列表（ids，旧消费方继续可用）——两条路线读同一份条目，不会漂移；
 		* 形状漂移抛 UPSTREAM_ERROR 并带 detail。
+		*
+		* `contextOverride`（tokens）是面板保存的全局上下文窗口覆盖：非 null 时在
+		* 归一**之前**改写每条原始条目——删掉目录可能携带窗口的四个原始拼写键、写上
+		* `contextWindow`。这是唯一能可靠生效的注入点：`normalizeEntry` 按
+		* `context_length/context_window/contextWindow/max_context_tokens` 顺序读
+		* 首个正数，任何只改归一后字段的窄打标都会被 `...source` 展开里的旧键回读
+		* 污染。删四键再写宽形状键，不依赖键序，目录声明与覆盖不可能同时在场。
+		* descriptor、roster、catalogSignature 都从这份归一条目派生，一处打标全链
+		* 路生效；签名含窗口值，覆盖变化自动触发重新注册。
+		*
+		* 覆盖值**参与缓存键**：coalesced 缓存里存的条目已是打标后的形状，若仍用
+		* 字面量 `"models"` 键，保存覆盖后的一个 TTL 内会读到未打标的旧条目（面板
+		* 显示变了、注册却没变）。带指纹后不同覆盖值各自缓存，互不串味。
+		*
+		* 窗口三级真值链（fetchModels 内单点判定）：目录声明 > 用户覆盖 >
+		* **策展表**（context-catalog，models.dev 交叉真值，零网络依赖）> 兜底
+		* 128k。目录声明过的条目任何下层都不碰；策展表只在用户没设覆盖时兜在
+		* 兜底之前——它是「更聪明的 128k」，不是新权威。
+		* @param {number|null} [contextOverride] - 全局窗口覆盖（tokens），null = 跟随目录。
 		*/
-		async fetchModels() {
+		async fetchModels(contextOverride) {
 			const url = settings.apiBase + "/models";
-			return await read("models", async () => {
+			return await read(`models:${contextOverride ?? "catalog"}`, async () => {
 				const response = await fetchWithTimeout(url, { method: "GET" });
 				if (!response.ok) {
 					const message = await readErrorMessage(response);
@@ -1265,10 +1611,34 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 				const entries = raws.map((raw) => {
 					const id = str(raw.id, "");
 					const tags = tagsById.get(id) ?? [];
-					return normalizeEntry({
+					const source = {
 						...raw,
 						tasks: tags.length > 0 ? tags : void 0
-					});
+					};
+					const CONTEXT_KEYS = [
+						"context_length",
+						"context_window",
+						"contextWindow",
+						"max_context_tokens"
+					];
+					if (!CONTEXT_KEYS.some((key) => {
+						const value = source[key];
+						return typeof value === "number" && Number.isFinite(value) && value > 0;
+					})) {
+						if (contextOverride != null) {
+							for (const key of CONTEXT_KEYS) delete source[key];
+							source.contextWindow = contextOverride;
+							source.__contextSource = "override";
+						} else {
+							const curated = curatedWindowOf(id);
+							if (curated !== null) {
+								for (const key of CONTEXT_KEYS) delete source[key];
+								source.contextWindow = curated;
+								source.__contextSource = "curated";
+							}
+						}
+					}
+					return normalizeEntry(source);
 				}).filter((entry) => entry.id !== "");
 				return {
 					entries,
@@ -1314,8 +1684,9 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 			}, settings.cacheSeconds * 1e3);
 		},
 		/**
-		* 一次 probe 调用：故意缺 messages 的请求，预期 401（令牌坏）先于 400
-		* （请求坏）返回，**零额度**鉴权探针（语义已真机回填，SPIKE.md）。
+		* 一次 probe 调用：故意缺 messages 的请求（**零额度**鉴权探针，语义已真机
+		* 回填，SPIKE.md）。魔搭**不先校验 messages**——缺 messages 返回 200（空壳）
+		* 而非 400，故判定规则是 401/403 = 令牌坏、200/400 = 令牌好、429 = 限频中。
 		*
 		* 失败抛 pluginError；调用方（probe 路由）负责把它记进事件流。
 		*/
@@ -1389,16 +1760,32 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 * Integrity follows `state-store.ts`: a versioned payload, a temp file plus an
 * atomic rename (two Host processes can share the directory), owner-only
 * modes, and "anything unrecognised reads as not set" — a corrupted or
-* downgraded file costs one re-toggle, never a crash.
+* downgraded file costs one re-toggle, never a crash. The write side refuses
+* to overwrite a version this build cannot read (ADR-006); the read side stays
+* permissive but REPORTS the disagreement via `versionNote()`, because for the
+* allow-list "unreadable" and "never saved" would otherwise collapse to the
+* same answer — and that answer is "offer every model".
 *
 * The allow-list's empty-vs-absent distinction is the one this module guards:
 * an EMPTY list means "no filter, offer every model", while `HIDE_ALL_MODELS`
 * (`llm-models.ts`) is the caller-side sentinel for "offer nothing". Neither
 * spelling is stored here as `null` — absence of a saved list reads as "no
-* filter", which is the only safe default for a fresh install.
+* filter", which is the only safe default for a fresh install. A foreign file
+* reads the same way, which is precisely why `versionNote()` exists.
 *
 * @module dsh-connect-modelscope-token-plan/provider-store
 */
+/**
+* The "nothing stored" payload. Every absent / unreadable / foreign read
+* 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 = {
+	enabled: null,
+	enabledIds: null,
+	contextWindow: null,
+	version: null
+};
 /** Shape version, bumped when the persisted form changes incompatibly. */
 const PROVIDER_VERSION = 1;
 /**
@@ -1406,12 +1793,36 @@ const PROVIDER_VERSION = 1;
 * historical ones. Bumping {@link PROVIDER_VERSION} means adding the new number
 * here too — otherwise this build would refuse its own newest files.
 *
-* This is the ADR-006 write-side guard's whitelist: an on-disk version not in
-* this list was written by a NEWER build, and must not be clobbered (see
-* {@link writePayload}).
+* This list is asked in THREE places:
+*   - the write side ({@link writePayload}, ADR-006): an on-disk version not in
+*     this list was written by a NEWER build and must not be clobbered. That
+*     caller asks `isKnownStateVersion(existing, ...)` rather than
+*     {@link isKnownProviderVersion} on purpose — it must also admit `null`
+*     ("no file at all"), which is the one situation where a write belongs.
+*   - the READ side ({@link parseAt}) and the report ({@link versionNote} /
+*     {@link describeProviderPayload}), which ask {@link isKnownProviderVersion}.
+* Keeping the read side and the report on one predicate is what makes them
+* unable to disagree about what a foreign version means.
 */
 const KNOWN_PROVIDER_VERSIONS = [1];
 /**
+* Whether this build can read a file declaring `version`.
+*
+* THE single answer to that question. Note it is deliberately NOT
+* `version === PROVIDER_VERSION`: the whitelist includes shapes this build can
+* read but no longer writes, so comparing against the write version would make a
+* version bump unreadable-of-its-own-files. The original bug behind this function
+* was exactly that split — `parseAt` compared against the write version while the
+* report asked the whitelist, so a bumped build read its own v1 files as "not
+* set" while its report said "nothing to say": the silent collapse the read side
+* exists to kill, resurrected by the upgrade procedure.
+* @param {unknown} version - the value read off disk (may not be a number at all).
+* @returns {boolean}
+*/
+function isKnownProviderVersion(version) {
+	return typeof version === "number" && KNOWN_PROVIDER_VERSIONS.includes(version);
+}
+/**
 * The directory this plugin's state lives in — per-profile when the Host names
 * one, shared otherwise. Unlike the THROTTLE, which is deliberately shared
 * across profiles, this answers "does THIS profile want the provider registered"
@@ -1431,6 +1842,18 @@ function normalizeEnabled(raw) {
 	return typeof raw === "boolean" ? raw : null;
 }
 /**
+* Normalize a context-window value: a positive finite number, or `null`
+* ("follow the catalog"). Anything else — strings, zero, negative, NaN,
+* Infinity — reads as no override, mirroring how {@link normalizeEnabled}
+* answers "nothing usable" instead of inventing a default.
+* @param {unknown} raw - the persisted or posted value.
+* @returns {number|null} the window in tokens, or `null` when nothing usable.
+*/
+function normalizeContextWindow(raw) {
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return null;
+	return raw;
+}
+/**
 * Normalize a persisted allow-list: an array of non-empty strings, de-duplicated
 * and order-preserved. Anything else reads as "no saved list".
 *
@@ -1454,6 +1877,33 @@ function normalizeEnabledIds(raw) {
 	return out;
 }
 /**
+* Resolve the allow-list to publish/display, from the persisted value and the
+* list this process last published.
+*
+* THE single answer to "which list wins", so that every consumer asks it the
+* same way: a READABLE persisted list wins — including an EMPTY one, because
+* this module's contract defines `[]` as "no filter, offer every model" — and
+* the in-memory list is consulted only when the persisted side could not be read
+* at all (the caller's `.catch` turns a rejection into `null`).
+*
+* The three call sites used to spell this out separately, and two of them had
+* drifted: `snapshot-aggregate.ts` and `routes/provider.ts` honoured an empty
+* persisted list, while `index.ts` treated it as "no answer" and republished the
+* remembered list. So after the operator deleted `provider.json` (the reset
+* `versionNote` itself recommends) the panel reported `allowed: "all"` — its
+* `enabledCount` counting every model — while the poller kept registering the
+* OLD restriction: the panel and the Host disagreeing about what is served,
+* which is precisely what the publish queue and the idle guards exist to
+* prevent. One copy now, asked by all three.
+* @param {unknown} stored - the persisted list, or `null` when unreadable.
+* @param {unknown} remembered - `publisher.state.enabledIds` (last published).
+* @returns {string[]} the list to use.
+*/
+function resolveEnabledIds(stored, remembered) {
+	if (Array.isArray(stored)) return stored;
+	return Array.isArray(remembered) ? remembered : [];
+}
+/**
 * The file-backed provider switch + allow-list.
 * @param {object} [options]
 * @param {string} [options.dir] - override the state directory (tests).
@@ -1477,40 +1927,92 @@ 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) => {
-		const existing = await readStateVersion(filePath);
-		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;
-	/** Read ONE payload off the disk, shape-checked. */
-	const parsePayload = async () => {
-		const raw = await readStateJson(filePath);
-		const source = obj(raw);
-		if (source.version !== 1) return {
+	/**
+	* Read ONE payload off the disk, shape-checked.
+	*
+	* "Can this build read it" is asked through {@link isKnownProviderVersion} —
+	* the same predicate the report and the write guard use. Comparing against
+	* {@link PROVIDER_VERSION} instead would say "cannot read" about the OLDEST
+	* shapes this build still knows, which is exactly wrong when it is bumped:
+	* the header's upgrade rule adds the new number to {@link KNOWN_PROVIDER_VERSIONS},
+	* so a v1 file must stay readable while v2 is written. Getting that wrong
+	* makes this reader disagree with {@link versionNote} — reads "not set" while
+	* the note says "nothing to say", which is the silent collapse this module
+	* exists to kill. That split once existed in production code for one release.
+	*
+	* A version this build cannot read reads as EMPTY, but REMEMBERS which version
+	* it was. The ADR-006 guard already refuses to overwrite such a file, so the
+	* read side has to be able to say "there is an answer in there, it just is
+	* not one we can see" — collapsing it to "never saved" is what made a saved
+	* allow-list look like a deliberate "offer every model". See {@link versionNote}.
+	*/
+	const parseAt = async (file) => {
+		const source = obj(await readStateJson(file));
+		const version = typeof source.version === "number" ? source.version : null;
+		if (!isKnownProviderVersion(version)) return {
 			enabled: null,
-			enabledIds: null
+			enabledIds: null,
+			contextWindow: null,
+			version
 		};
 		return {
 			enabled: normalizeEnabled(source.enabled),
-			enabledIds: normalizeEnabledIds(source.enabledIds)
+			enabledIds: normalizeEnabledIds(source.enabledIds),
+			contextWindow: normalizeContextWindow(source.contextWindow),
+			version
 		};
 	};
+	/** Read the profile's own file, shape-checked. */
+	const parsePayload = async () => parseAt(filePath);
+	/** Read one payload off an explicit path (the legacy shared file). */
+	const parsePayloadFrom = async (file) => parseAt(file);
+	const writeQueue = createStateWriteQueue();
+	const cache = createStateReadCache(async () => {
+		const own = await parsePayload();
+		if (own.enabled !== null || own.enabledIds !== null || legacyFile === null) return own;
+		if (own.version !== null) return own;
+		const legacy = await parsePayloadFrom(legacyFile);
+		if (legacy.enabled === null && legacy.enabledIds === null) return own;
+		const inherited = {
+			version: 1,
+			...legacy.enabled === null ? {} : { enabled: legacy.enabled },
+			...legacy.enabledIds === null ? {} : { enabledIds: legacy.enabledIds },
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await writeQueue.enqueue(() => writePayload(inherited).then(() => void 0, () => void 0));
+		return legacy;
+	}, { ttlMs });
+	const read = () => cache.read();
+	/**
+	* The payload the callers actually read. The short-TTL cache's `read()` is
+	* typed `Promise<T | null>` because it doubles as "never read" signalling for
+	* the §23 legacy adoption; a provider payload is always an object, so the
+	* `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;
 	/**
-	* Read one payload, then hand it to `write` — the read-modify-write that keeps
-	* the switch and the list from clobbering each other.
+	* Read one payload, then hand it to {@link writePayload} — the read-modify-
+	* write that keeps the switch and the list from clobbering each other.
 	*
 	* Three-state keys, and they are SYMMETRIC between `enabled` and `enabledIds`:
 	* a key the caller omits (`undefined`) keeps whatever is on disk, an explicit
@@ -1519,28 +2021,30 @@ function createFileProviderStore(options = {}) {
 	* value is stored as given. An earlier `mergeEnabled` flag applied the
 	* "keep what is on disk" rule to `enabled` unconditionally, which silently
 	* discarded the very value a switch save was asked to store.
-	* @param {object} patch - `{ enabled?, enabledIds? }` to persist.
-	* @returns {Promise<string|null>} the write refusal reason, or `null`.
-	*/
-	/**
-	* 读-改-写**整段排队**：两个并发patch 不能互相覆盖。
-	*
-	* 这个 store 以前完全没有写串行化（对比 `usage-store.ts` 的 `writeChain`），于是
-	* 面板开关POST 与 roster POST —— 两个独立请求，外加 `index.ts` 轮询同时在调
-	* `enabledIds()` —— 会各自读到同一个 `current`，后写的赢。实测：先存清单，再并发
-	* `save(true)` + `saveEnabledIds([...])`，其中一次保存被**整个丢掉**（用户勾了
-	* 模型又开了开关，两次点击只活下来一次）。
 	*
-	* 文件头说「两个字段必须作为一个载荷读写，否则开关会覆盖清单」——设计意图是对的，
-	* 但那只防住了「**不同字段**互相覆盖」；缺了串行化，**同字段**与「两次都基于同一
-	* 快照」的互相覆盖照样发生。链的形状与 `usage-store` 一致，且必须把
-	* `writePayload` 的版本拒绝语义一起搬进临界区（否则拒绝判断会落在锁外）。
+	* 读-改-写**整段排队**：两个并发 patch 不能互相覆盖。这个 store 以前完全没有
+	* 写串行化（对比 `usage-store.ts` 的 `writeChain`），于是面板开关 POST 与
+	* roster POST —— 两个独立请求，外加 `index.ts` 轮询同时在调 `enabledIds()` ——
+	* 会各自读到同一个 `current`，后写的赢。实测：先存清单，再并发 `save(true)` +
+	* `saveEnabledIds([...])`，其中一次保存被**整个丢掉**（用户勾了模型又开了开关，
+	* 两次点击只活下来一次）。文件头说「两个字段必须作为一个载荷读写，否则开关会
+	* 覆盖清单」——设计意图是对的，但那只防住了「**不同字段**互相覆盖」；缺了串行化，
+	* **同字段**与「两次都基于同一快照」的互相覆盖照样发生。链的形状与
+	* `usage-store` 一致，且必须把 `writePayload` 的版本拒绝语义一起搬进临界区
+	* （否则拒绝判断会落在锁外）。
 	*
 	* 链吞掉自己的失败继续走：一次只读 Home 上的写失败不该毒化后续所有保存。
+	*
+	* 写成功的同时更新读缓存，调用方不再各自回读一遍：缓存里永远是刚写下去的那份，
+	* 而 `patchPayload` 的 `current` 来自磁盘（`parsePayload`，不走缓存），所以合并
+	* 结果不会带进过期值。此前的写法是写完再 `readPayload()` 读回另一半——那条回读
+	* 走的是 TTL 缓存，拿到的是**写入前**的值，并发时会把一个较新的缓存项顶成旧值。
+	*
+	* @param {object} patch - `{ enabled?, enabledIds?, contextWindow? }` to persist.
+	* @returns {Promise<string|null>} the write refusal reason, or `null`.
 	*/
-	let writeChain = Promise.resolve(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 };
@@ -1548,50 +2052,18 @@ function createFileProviderStore(options = {}) {
 			if (enabled !== null) body.enabled = enabled;
 			const enabledIds = patch.enabledIds === void 0 ? current.enabledIds : patch.enabledIds;
 			if (enabledIds !== null) body.enabledIds = enabledIds;
+			const contextWindow = patch.contextWindow === void 0 ? current.contextWindow : patch.contextWindow;
+			if (contextWindow !== null) body.contextWindow = contextWindow;
 			body.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-			return writePayload(body);
+			const refusal = await writePayload(body);
+			if (refusal === null) cache.remember({
+				enabled,
+				enabledIds,
+				contextWindow,
+				version: 1
+			});
+			return refusal;
 		});
-		writeChain = run.catch(() => null);
-		return run;
-	};
-	const cache = createStateReadCache(async () => {
-		const own = await parsePayload();
-		if (own.enabled !== null || own.enabledIds !== null || legacyFile === null) return own;
-		const legacy = await parsePayloadFrom(legacyFile);
-		if (legacy.enabled === null && legacy.enabledIds === null) return own;
-		const inherited = {
-			version: 1,
-			...legacy.enabled === null ? {} : { enabled: legacy.enabled },
-			...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));
-		return legacy;
-	}, { ttlMs });
-	const read = () => cache.read();
-	/**
-	* The payload the callers actually read. The short-TTL cache's `read()` is
-	* typed `Promise<T | null>` because it doubles as "never read" signalling for
-	* the §23 legacy adoption; a provider payload is always an object, so the
-	* `null` branch collapses here, in one place, rather than at every caller.
-	* @returns {Promise<ProviderPayload>} the payload; `{enabled:null,enabledIds:null}` when nothing is stored.
-	*/
-	const readPayload = async () => await read() ?? {
-		enabled: null,
-		enabledIds: null
-	};
-	/** Read one payload off an explicit path (the legacy shared file). */
-	const parsePayloadFrom = async (file) => {
-		const raw = await readStateJson(file);
-		const source = obj(raw);
-		if (source.version !== 1) return {
-			enabled: null,
-			enabledIds: null
-		};
-		return {
-			enabled: normalizeEnabled(source.enabled),
-			enabledIds: normalizeEnabledIds(source.enabledIds)
-		};
 	};
 	return {
 		/**
@@ -1610,6 +2082,16 @@ function createFileProviderStore(options = {}) {
 			return (await readPayload()).enabledIds ?? [];
 		},
 		/**
+		* The saved context-window override (tokens), or `null` = follow the
+		* catalog. `null` is a real answer here, not absence: the override is
+		* optional by design, and the caller (snapshot / stamping) decides what
+		* "follow the catalog" means.
+		* @returns {Promise<number|null>}
+		*/
+		async contextWindow() {
+			return (await readPayload()).contextWindow;
+		},
+		/**
 		* Whether the panel has ever saved a value here.
 		* @returns {Promise<boolean>}
 		*/
@@ -1618,6 +2100,33 @@ function createFileProviderStore(options = {}) {
 			return payload.enabled !== null || payload.enabledIds !== null;
 		},
 		/**
+		* A human-readable note when the file holds a version this build cannot
+		* read, or `null` when there is nothing to say.
+		*
+		* The READ side is permissive on purpose: a foreign file reads as "not set",
+		* so the panel keeps working instead of failing the whole snapshot. The cost
+		* is that it cannot tell "never saved" from "saved but unreadable" — and
+		* for the allow-list those two read differently in the dangerous direction
+		* (an empty list means "offer every model"). Writes are already protected by
+		* the ADR-006 guard in {@link writePayload}; this note is the read side's
+		* half of the same promise. The snapshot aggregate pushes it into
+		* `shapeWarnings`, and `doctor.ts` reports the same file, so the operator
+		* sees the disagreement instead of a switch that looks merely unset.
+		*
+		* @returns {Promise<string|null>}
+		*/
+		async versionNote() {
+			const version = (await readPayload()).version;
+			if (version === null || isKnownProviderVersion(version)) return null;
+			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
 		* concurrent reader never sees a partial payload, and it PRESERVES the
 		* saved allow-list.
@@ -1629,10 +2138,6 @@ function createFileProviderStore(options = {}) {
 			if (enabled === null) throw new TypeError("provider switch expects a boolean");
 			const refusal = await patchPayload({ enabled });
 			if (refusal !== null) throw new Error(refusal);
-			cache.remember({
-				enabled,
-				enabledIds: (await readPayload()).enabledIds ?? []
-			});
 		},
 		/**
 		* Persist the model allow-list, preserving the saved switch.
@@ -1644,75 +2149,1221 @@ function createFileProviderStore(options = {}) {
 			if (list === null) throw new TypeError("provider allow-list expects an array of strings");
 			const refusal = await patchPayload({ enabledIds: list });
 			if (refusal !== null) throw new Error(refusal);
-			cache.remember({
-				enabled: (await readPayload()).enabled ?? null,
-				enabledIds: list
-			});
+		},
+		/**
+		* Persist the context-window override, preserving the saved switch and
+		* allow-list. `null` clears the override back to "follow the catalog".
+		* @param {number|null} value - the window in tokens, or `null` to clear.
+		* @returns {Promise<void>}
+		*/
+		async saveContextWindow(value) {
+			const window = normalizeContextWindow(value);
+			if (value !== null && window === null) throw new TypeError("provider context window expects a positive finite number");
+			const refusal = await patchPayload({ contextWindow: window });
+			if (refusal !== null) throw new Error(refusal);
 		},
 		/**
 		* Forget the panel-saved values: the config default and "no filter" rule
-		* again.
+		* again. The context override is forgotten WITH them — the reset button
+		* means "back to the way this plugin ships", and the override is panel
+		* state in exactly the same sense.
 		* @returns {Promise<void>}
 		*/
 		async forget() {
 			const refusal = await patchPayload({
 				enabled: null,
-				enabledIds: null
+				enabledIds: null,
+				contextWindow: null
 			});
 			if (refusal !== null) throw new Error(refusal);
-			cache.remember({
-				enabled: null,
-				enabledIds: null
-			});
 		}
 	};
 }
 
 //#endregion
-//#region src/host/switch-precedence.ts
+//#region src/host/draw-store.ts
 /**
-* The single adjudicator for "panel-saved value vs config default" across
-* every opt-in switch.
+* 出图工具的开关与模型偏好——本插件**自己的**状态文件，与 provider 那条开关分开。
 *
-* Historically the rule was hand-copied at three call sites (the provider
-* route, the models route, the draw route) in two look-alike dialects:
+* 为什么不是第二个字段塞进 `provider.json`：两者回答的是不同问题。
+* `provider.json` 说「这个 profile 要不要把魔搭作为 **chat provider** 提供」；
+* 本文件说「要不要给 agent 一个**出图工具**」。用户完全可能只要其一（用工具出图但
+* 不污染模型选择器，或反之）。合成一个 payload 会让「关掉出图」连带改掉 provider
+* 清单的写入时序——provider-store 的注释已说明为什么它的两个字段必须同生共死，
+* 而那组理由**不适用于**这两个开关（它们之间没有 atomicity 要求）。
 *
-*   - the boolean switch: `(panel ?? config) === true` plus
-*     `panel === null ? "config" : "panel"`;
-*   - the model preference: `panel ?? config` plus the same source probe.
+* 落点与 `provider-store.ts` 一致：`$DSH_HOME/state/<plugin>/draw.json`（无 profile
+* 时）或 `$DSH_HOME/state/<profile>/<plugin>/draw.json`。profile 分段的意思是
+* 「这个 profile 要不要暴露出图工具」，两个 profile 不能互相覆盖。
 *
-* A fourth dialect existed where no config default exists at all (a switch that
-* is purely panel-owned — a profile without a saved value falls to `off` with no
-* fallback), which is exactly the shape this module does NOT serve: that one has
-* no config default to adjudicate against, so it is the caller's plain read.
+* 优先级与所有 opt-in 开关同一份裁决（`switch-precedence.ts`）：面板保存值赢，
+* 否则 `cordis.patch.yml` 的 `drawEnabled` 默认值说了算。
 *
-* This module is peer-free and deliberately tiny: the whole point is that a
-* switch can never again invent its own precedence dialect, and the source
-* label (`panel` / `config`) always rides with the answer so the panel can
-* say which side is in charge. `test/switch-precedence.test.mjs` pins the
-* dialect so a new caller copying the shape is the odd one out.
+* 完整性三件套（与 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`——不说，面板就把「保存的
+*     值被忽略」呈现成「从未保存过」。
 *
-* 注：本模块自带的 `test/switch-precedence.test.mjs` 钉死纯函数行为；部分旧注释里
-* 提到的 `test/peer-contract.test.mjs`（钉死真 peer 的 classifyPiAiError /
-* resolveRetryPolicy 协议）依赖未 vendored 进本仓库的运行时 peer，不在 `npm test`
-* 离线门禁内。
+* 与 provider-store 的一处**有意差异**：没有 legacy（pre-profile 共享目录）继承。
+* draw.json 随出图工具一起诞生，晚于按 profile 分段，市面上不存在共享布局里的
+* 旧 draw.json；provider.json 则需要（§23 之前它一直在共享目录）。
 *
-* @module dsh-connect-modelscope-token-plan/switch-precedence
+* doctor 覆盖：`describeDrawPayload` 给只读速览，`doctor.ts` 据此把 draw.json
+* 的「损坏 / 未知版本」报进症状表——写侧守卫挡覆盖，doctor 报静默降级。
+*
+* @module dsh-connect-modelscope-token-plan/draw-store
 */
+/** 本 store 落盘 payload 的版本。 */
+const DRAW_STORE_VERSION = 1;
+/** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
+const KNOWN_DRAW_VERSIONS = Object.freeze([1]);
+const EMPTY_PAYLOAD = {
+	enabled: null,
+	modelId: null,
+	version: 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.
+* 本 build 读不读得懂这个版本。
+*
+* 与 provider-store 的 {@link isKnownProviderVersion} 同形：**白名单**判据，
+* 不与 {@link DRAW_STORE_VERSION} 比较——升级后旧号仍要可读。读侧（parseAt）、
+* 报告侧（versionNote / describeDrawPayload）问的都是这一个函数，三者不可能就
+* 「什么是未知版本」说两套话。写侧问的是 `state-store` 的
+* `isKnownStateVersion`（它额外放行 `null` = 没有文件，那是唯一该写的情形）。
+* @param {unknown} version - 盘上读到的值（可能根本不是数字）。
+* @returns {boolean}
 */
-function resolveSwitchEnabled(panel, config) {
-	return (panel ?? config) === true;
+function isKnownDrawVersion(version) {
+	return typeof version === "number" && KNOWN_DRAW_VERSIONS.includes(version);
 }
 /**
-* 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.
+* 归一一个保存的模型偏好：非空字符串，或 `null`（= 自动挑——具体挑谁由
+* `draw-runtime.ts` 的 `pickDrawModel` 优先级决定，不是简单取目录第一个）。
+*
+* 不校验「这个 id 是否真存在」——目录会变，存一个暂时不在目录里的 id 是合法的
+* （用户可能先配好、等模型上线）。调用侧解析不出来时退回自动。
+* @param {unknown} value - 原始值。
+* @returns {string|null} 归一后的 id 或 `null`。
+*/
+function normalizeDrawModelId(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
+/**
+* 归一保存的开关值：只有真正的 boolean 才算数，其余读作「没设过」。
+* @param {unknown} value - 原始值。
+* @returns {boolean|null} 归一后的开关。
+*/
+function normalizeDrawEnabled(value) {
+	return typeof value === "boolean" ? value : null;
+}
+/** 本 store 的目录（与 provider-store 同一套分段规则）。 */
+function drawStoreDir(profile, dir) {
+	if (typeof dir === "string" && dir !== "") return dir;
+	return profile ? profileStateDir(name, profile) : stateDir(name);
+}
+/**
+* 文件支撑的出图开关 + 模型偏好。
+* @param {StoreOptions} [options] - `{ dir, profile, ttlMs, logger }`。
+* @returns {object} store 句柄。
+*/
+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");
+	/**
+	* 写一份补丁并落盘（内部用；对调用方暴露的是 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;
+		if (!isKnownDrawVersion(version)) return {
+			enabled: null,
+			modelId: null,
+			version
+		};
+		return {
+			enabled: normalizeDrawEnabled(source.enabled),
+			modelId: normalizeDrawModelId(source.modelId),
+			version
+		};
+	};
+	const cache = createStateReadCache(parsePayload, { ttlMs });
+	/**
+	* 读当前 payload。
+	* @returns {Promise<DrawPayload>}
+	*/
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	/**
+	* 读-改-写一份补丁，**整段排队**。
+	*
+	* 基线每次从磁盘重读（`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 = (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 readPayload()).enabled;
+		},
+		/** 面板保存的模型偏好；`null` = 自动。 */
+		async modelId() {
+			return (await readPayload()).modelId;
+		},
+		/** 这个 profile 是否被显式配置过。 */
+		async isConfigured() {
+			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");
+			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");
+			await patchPayload({ modelId });
+		},
+		/** 清掉两个字段（回到「没配过」）。 */
+		async reset() {
+			await patchPayload({
+				enabled: null,
+				modelId: null
+			});
+		},
+		/** 落盘路径（诊断与测试用）。 */
+		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 - 规范化状态。
+* @returns {boolean} 是否终态。
+*/
+function isTerminalStatus(status) {
+	return status === "SUCCEED" || status === "FAILED";
+}
+/**
+* 从提交响应里取 `task_id`。
+*
+* 提交响应里那个 `task_status: "SUCCEED"` **一律忽略**（见模块头第 2 条：它与终态
+* 无关）。本函数只认 `task_id`，所以一个「提交即失败」的上游只要给了 id 就仍会被
+* 轮询，而不给 id 会被当作提交失败——这两种都符合实测。
+* @param {unknown} data - 已解析的提交响应。
+* @returns {string|null} 任务 id，取不到为 `null`。
+*/
+function readTaskId(data) {
+	if (data === null || typeof data !== "object") return null;
+	const raw = data.task_id;
+	return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+/**
+* 从终态响应里取出成品图的 URL 列表。
+*
+* 实测形状是顶层 `output_images: string[]`。**刻意不读** `data[0].url`（OpenAI
+* 同步形状）与 `output.image_url`（外部资料误传的形状）——两者在魔搭上都不存在。
+* @param {unknown} data - 已解析的轮询响应。
+* @returns {string[]} 可用的图片 URL（保持上游顺序，已去空）。
+*/
+function readOutputImages(data) {
+	if (data === null || typeof data !== "object") return [];
+	const raw = data.output_images;
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) if (typeof item === "string" && item.trim() !== "") out.push(item.trim());
+	return out;
+}
+/**
+* 构造出图请求体。
+*
+* 只发上游**确认消费**的字段：`model` / `prompt` / `image_url` / `size` / `steps` /
+* `guidance` / `seed` / `negative_prompt` 均被实测接受（SPIKE 实测 #9）；`loras`
+* 也被确认消费（无效 LoRA id 在提交阶段直接 500，实测 #18）。**不发** `ref_image`
+* ——那是别家平台的写法，魔搭上不存在（SPIKE §对照）。
+*
+* `image_url` **一律发数组**，哪怕只有一张：官方示例的形状是数组（多图编辑要用），
+* 实测单张以数组发也通（#17）、以裸字符串发亦通（#8）。取数组是因为它的超集更贴近
+* 上游本意，也省掉一个分支。
+*
+* `n` 刻意**不作为请求字段**：实测目录里的出图模型都是单出模型，`n` 的支持度未
+* 逐项验证，传一个上游不认的参数比不传更危险。调用方要几张就发几次。
+* @param {object} options - 请求参数。
+* @param {string} options.model - 模型 id。
+* @param {string} options.prompt - 提示词。
+* @param {string|string[]} [options.imageUrl] - 输入图 URL，**字符串或数组均可**，
+*   内部一律归一为数组（官方形状；多图编辑要用数组）。
+* @param {string} [options.size] - `"宽x高"`，如 `"1024x1024"`（64 对齐）。
+* @param {number} [options.steps] - 采样步数。
+* @param {number} [options.guidance] - 引导系数。
+* @param {number} [options.seed] - 随机种子。
+* @param {string} [options.negativePrompt] - 负向提示词。
+* @param {string|Record<string, number>} [options.loras] - LoRA 配置：单个 repo id，
+*   或 `{id: weight}` 映射（官方：最多 6 个，权重和须为 1.0）。
+* @returns {object} 请求体。
+*/
+function buildDrawBody(options) {
+	const body = {
+		model: str(options.model, ""),
+		prompt: str(options.prompt, "")
+	};
+	const imageUrl = normalizeImageUrlList(options.imageUrl);
+	if (imageUrl.length > 0) body.image_url = imageUrl;
+	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 = str(options.negativePrompt, "");
+	if (negativePrompt !== "") body.negative_prompt = negativePrompt;
+	const loras = options.loras;
+	if (typeof loras === "string" && loras.trim() !== "") body.loras = loras.trim();
+	else if (loras !== null && typeof loras === "object") {
+		const entries = Object.entries(loras).filter(([id, weight]) => id.trim() !== "" && Number.isFinite(weight));
+		if (entries.length > 0) body.loras = Object.fromEntries(entries);
+	}
+	return body;
+}
+/**
+* 把「一张或多张输入图」归一成 URL 数组。
+*
+* 单张给字符串上游也吃（实测 #8），但官方示例与多图编辑都用数组（#17 实测通），
+* 故一律归一为数组。逐项过滤空串，**保持调用方给定的顺序**——多图编辑里顺序即语义
+* （官方示例：「图一中的狗，去追图二中的飞盘」）。
+* @param {unknown} value - 单个 URL、URL 数组，或缺省。
+* @returns {string[]} 归一后的 URL 数组（可为空）。
+*/
+function normalizeImageUrlList(value) {
+	const raw = Array.isArray(value) ? value : [value];
+	const out = [];
+	for (const item of raw) if (typeof item === "string" && item.trim() !== "") out.push(item.trim());
+	return out;
+}
+/**
+* 从任意配置里读出「可用作输入图」的 URL。
+*
+* 承接 agent 工具的 `image_url` 参数。**只接受 http(s) 与 data URL**——其它形态
+* （本地路径）上游取不到，转发过去只会换回一个原因不可知的 `FAILED`。实测尚未
+* 验证 data URL 是否被上游接受（SPIKE 待办），但**转发它不会更糟**，而拦掉它会让
+* 本地图片彻底不可用；故放行并在档案里留待验证。
+* @param {unknown} value - 原始参数。
+* @returns {string|null} 规范化后的 URL，不可用时为 `null`。
+*/
+function normalizeImageUrlInput(value) {
+	const raw = typeof value === "string" ? value.trim() : "";
+	if (raw === "") return null;
+	if (/^https?:\/\//i.test(raw)) return raw;
+	if (/^data:image\/[a-z0-9.+-]+;base64,/i.test(raw)) return raw;
+	return null;
+}
+/**
+* 把一次失败转成 agent 与面板都能读的一句话。
+*
+* **关于魔搭 `FAILED` 的诚实边界**：实测唯一的失败样本是
+* `{"errors":{"code":0,"message":""}, "task_status":"FAILED"}`——**原因不可知**。
+* 所以这里只报「可确定的形态事实」（HTTP 码 / 轮询未出终态 / 明确的原因文本），
+* **不从空错误里编造原因**，并在原因确实拿不到时明说「上游未给出原因」。这是本仓库
+* README「诚实声明」的要求。
+*
+* 凭据永不入消息：body 文本可能回显 `ms-` 令牌，过 `redactSecrets` 后再截断。
+* @param {object} failure - 失败信息。
+* @param {number} [failure.status] - HTTP 状态码（提交/轮询的传输层失败）。
+* @param {string} [failure.bodyText] - 上游 body 原文。
+* @param {string} [failure.taskStatus] - 轮询读到的状态。
+* @param {string} [failure.cause] - 已知原因（超时 / 没有可用图片 / 拿不到 task_id 等）。
+* @returns {string} 一行说明。
+*/
+function describeDrawFailure(failure) {
+	const text = redactSecrets(typeof failure.bodyText === "string" ? failure.bodyText : "").slice(0, 300);
+	const status = Number.isFinite(failure.status) ? Number(failure.status) : 0;
+	const tail = text === "" ? "" : `; body: ${text}`;
+	if (status === 401 || status === 403) return `出图失败：HTTP ${status} —— 访问令牌无效、无权访问该模型，或账号未完成邮箱验证/实名（后者是实测遇到过的真实拦截）。请在面板确认令牌与账号状态${tail}`;
+	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 = str(failure.cause, "");
+	if (cause !== "") return `出图失败：${cause}${tail}`;
+	const taskStatus = str(failure.taskStatus, "");
+	if (taskStatus === "FAILED") return "出图失败：上游任务 FAILED，但未给出失败原因（实测 errors.code=0、message 为空），换模型或稍后重试";
+	if (taskStatus !== "") return `出图失败：任务停在 ${taskStatus}（非终态），已超过截止时间`;
+	return `出图失败：上游未给出可诊断的失败信息${tail}`;
+}
+/**
+* 冷却门：一次失败后的一段时间内拒绝再试。
+*
+* 借 sensenova 那份的形状（它也从 `dsh-draw-router` 抄来）：出图慢且贵，一次失败
+* 后立刻重试既容易撞限流又浪费等待窗口。纯闭包，无依赖，可离线测。
+* @param {number} cooldownMs - 冷却窗口（毫秒）。
+* @returns {{fail: () => void, remainingMs: () => number, clear: () => void}} 冷却门。
+*/
+function createDrawCooldown(cooldownMs) {
+	const window = Math.max(0, Math.floor(cooldownMs));
+	let until = 0;
+	return {
+		/** 记一次失败，从此刻起进入冷却。 */
+		fail() {
+			until = Date.now() + window;
+		},
+		/** 剩余冷却毫秒；0 表示可以发起。 */
+		remainingMs() {
+			return Math.max(0, until - Date.now());
+		},
+		/** 清掉冷却（例如面板里手动排障后）。 */
+		clear() {
+			until = 0;
+		}
+	};
+}
+
+//#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
+//#region src/host/draw-runtime.ts
+/**
+* 出图的 **peer-dependent 半边**：真正发起请求、驱动异步两段式、注册成 agent 工具。
+*
+* 与 `llm-adapter.ts` 同一个处境——import Host 发行的 peer（`@deepseek-ai/dsh-tools`
+* 的 `defineTool` 由调用方惰性注入），**不能由离线单测套件导入**。纯逻辑全部住在
+* `draw.ts`（已由 `test/draw.test.mjs` 覆盖 39 组），本文件只做「接线 + I/O」：
+* 轮询循环、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` 就结束。魔搭是
+* **异步两段式**：提交拿 `task_id`，再轮询到终态取 `output_images[0]`。所以这里多
+* 一个 `pollTask` 循环，且它必须带 `X-ModelScope-Task-Type`（漏了 = 假失败）。
+*
+* 三条承重纪律：
+* 1. 提交响应的 `task_status` **一律忽略**（实测恒为 SUCCEED，连最终 FAILED 的那次
+*    也是），成功与否只看轮询终态。`readTaskId` 已把这条钉在纯逻辑层。
+* 2. 轮询间隔 15s（`DRAW_POLL_INTERVAL_MS`），**不是**社区常见的 5s——实测更密的
+*    轮询只与更慢相关。
+* 3. 失败原因实测可能**不可知**（`errors.code:0` + 空 message）。`describeDrawFailure`
+*    因此明说「未给出原因」，本文件也**不从空错误里编造**。
+*
+* @module dsh-connect-modelscope-token-plan/draw-runtime
+*/
+/** 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;
+/**
+* 把 OpenAI 兼容 base 拼成出图端点。
+*
+* `…/v1` → `…/v1/images/generations`；已带该后缀则原样；更深路径回卷到 `/v1`。
+* 与 sensenova 的同名函数同源（那是受控复制：endpoint 拼接与上游是谁无关）。
+* @param {string} apiBase - 配置里的 apiBase。
+* @returns {string} 完整端点。
+*/
+function buildGenerationsEndpoint(apiBase) {
+	const trimmed = str(apiBase, "").replace(/\/+$/, "");
+	if (/\/images\/generations$/.test(trimmed)) return trimmed;
+	if (/\/v1$/.test(trimmed)) return `${trimmed}/images/generations`;
+	if (/\/v1\//.test(trimmed)) return trimmed.replace(/\/v1\/.*$/, "/v1/images/generations");
+	return `${trimmed}/v1/images/generations`;
+}
+/**
+* 拼轮询端点。task_id 上游是 UUID（实测失败态出现过短 id），一律走 path。
+* @param {string} apiBase - 配置里的 apiBase。
+* @param {string} taskId - 任务 id。
+* @returns {string} 完整端点。
+*/
+function buildTasksEndpoint(apiBase, taskId) {
+	return `${buildGenerationsEndpoint(apiBase).replace(/\/images\/generations$/, "")}/tasks/${encodeURIComponent(taskId)}`;
+}
+/**
+* 一个响应体到底是不是「终态」——读不到就当还没好，继续等。
+*
+* 与 `isTerminalStatus` 的分工：那个管状态语义，这个管「响应本身能不能读」。
+* 上游偶发返回非 JSON（CDN 错误页）时，当作暂时性抖动继续等，而不是判失败——
+* 实测过一个 task 在正常轮询下始终 SUCCEED，没有理由把一次解析失败升级成终局。
+* @param {unknown} data - 已解析的 JSON。
+* @returns {boolean} 是否终态。
+*/
+function isTerminalPayload(data) {
+	return isTerminalStatus(readTaskStatus(data));
+}
+/**
+* **第一段**：提交一次出图，只要 `task_id`。
+*
+* 提交必须带 `X-ModelScope-Async-Mode`（实测可省但官方示例都带，带上无害）。
+* 响应里的 `task_status` **一律忽略**——实测恒为 `SUCCEED`，连最终 `FAILED` 的那次
+* 也是，所以成功与否只看轮询终态（这条由 `readTaskId` 钉在纯逻辑层）。
+* @param {DrawSubmitInput} input - 提交参数。
+* @returns {Promise<{taskId: string}>} 上游任务 id（= 续查用的 jobId）。
+* @throws {Error} 提交失败——消息已过 `describeDrawFailure`。
+*/
+async function submitDrawTask({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl, size, steps, guidance, seed, negativePrompt }) {
+	const headers = {
+		Authorization: `Bearer ${apiKey}`,
+		"Content-Type": "application/json"
+	};
+	const body = buildDrawBody({
+		model,
+		prompt,
+		...imageUrl !== void 0 ? { imageUrl } : {},
+		...size !== void 0 ? { size } : {},
+		...steps !== void 0 ? { steps } : {},
+		...guidance !== void 0 ? { guidance } : {},
+		...seed !== void 0 ? { seed } : {},
+		...negativePrompt !== void 0 ? { negativePrompt } : {}
+	});
+	let submitted;
+	try {
+		submitted = await fetchImpl(buildGenerationsEndpoint(apiBase), {
+			method: "POST",
+			headers: {
+				...headers,
+				"X-ModelScope-Async-Mode": "true"
+			},
+			body: JSON.stringify(body)
+		});
+	} catch (error) {
+		throw new Error(describeDrawFailure({ cause: `提交请求失败：${error instanceof Error ? error.message : String(error)}` }));
+	}
+	const submitText = await safeText(submitted);
+	if (!submitted.ok) throw new Error(describeDrawFailure({
+		status: submitted.status,
+		bodyText: submitText
+	}));
+	const taskId = readTaskId(await safeJson(submitted, submitText));
+	if (taskId === null) throw new Error(describeDrawFailure({
+		bodyText: submitText,
+		cause: "提交响应里没有 task_id"
+	}));
+	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) return {
+			kind: "pending",
+			polls
+		};
+		await sleep(interval);
+		polls++;
+		let polled;
+		try {
+			polled = await fetchImpl(buildTasksEndpoint(apiBase, taskId), {
+				method: "GET",
+				headers: {
+					...headers,
+					[TASK_TYPE_HEADER]: TASK_TYPE_IMAGE_GENERATION
+				}
+			});
+		} catch {
+			continue;
+		}
+		const pollText = await safeText(polled);
+		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") return {
+			kind: "failed",
+			message: describeDrawFailure({
+				taskStatus: "FAILED",
+				bodyText: pollText
+			})
+		};
+		const images = readOutputImages(data);
+		if (images.length === 0) return {
+			kind: "failed",
+			message: describeDrawFailure({
+				taskStatus: "SUCCEED",
+				bodyText: pollText,
+				cause: "任务报 SUCCEED 但没有可用图片"
+			})
+		};
+		return {
+			kind: "done",
+			images,
+			polls
+		};
+	}
+}
+/**
+* 从目录里挑一个出图模型。
+*
+* 优先级（高 → 低）：
+* 1. **工具显式请求**——即使不在目录里也放行（手工覆盖，上游会自己报错）；
+* 2. **首选模型**（面板保存的模型偏好，或配置 `drawModelId`）——用户点了谁就是
+*    谁，同样不校验在不在目录（用户可能先配好、等模型上线）。此前这个偏好只在
+*    `pickDrawModel` 返回 null 时才生效，目录非空时等于死配置——面板显示的
+*    preferredModel 与实际挑中的模型会说两套话；
+* 3. 目录里**平台声明**为 `text-to-image` 的条目（`textToImageModelIds`，将来目录
+*    补上真文生图模型时自动优先生效）；
+* 4. **已知能纯文生图**的模型（`KNOWN_T2I_MODEL_ID`）——今天目录的坑位，见该
+*    常量的注释：真实目录里它是第二个，照旧取「第一个」会挑中纯文生图必挂的
+*    `MusePublic/…`；
+* 5. 目录里第一个出图模型（`isImageGenModel` 的严格方向：只认明确声明，缺字段
+*    不算）。
+*
+* 目录为空且既无显式请求也无首选模型 → `null`，由调用方给出可操作的错误，
+* 而不是发一个注定失败的请求。
+* @param {unknown} entries - 归一目录条目。
+* @param {string} [requested] - 工具调用里显式给的 model。
+* @param {string} [preferred] - 首选模型 id（面板偏好或配置 `drawModelId`）。
+* @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;
+}
+/**
+* 目录里可用于出图的模型 id（工具结果里回显，方便 agent 与用户看到实际候选）。
+* @param {unknown} entries - 归一目录条目。
+* @returns {string[]} id 列表。
+*/
+function drawModelIds(entries) {
+	return imageGenModelIds(entries);
+}
+/**
+* 装配 agent 工具定义——**两段式**，一次调用不再阻塞整轮对话。
+*
+* ## 为什么是两段式
+*
+* 上游出图要排队，实测 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, 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), 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. 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). 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",
+				description: "ModelScope image model id; defaults to the catalogue's image model"
+			},
+			imageUrl: {
+				type: "string",
+				description: "Input image URL for editing (public http(s) or data:image/...;base64). For multi-image editing pass several URLs separated by newlines — order is significant."
+			},
+			size: {
+				type: "string",
+				description: "Image size as WIDTHxHEIGHT, e.g. 1024x1024 (64-aligned)"
+			},
+			steps: {
+				type: "number",
+				description: "Sampling steps (platform range 1-100)"
+			},
+			guidance: {
+				type: "number",
+				description: "Prompt guidance scale (platform range 1.5-20)"
+			},
+			seed: {
+				type: "number",
+				description: "Random seed"
+			},
+			negativePrompt: {
+				type: "string",
+				description: "Negative prompt"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					source: { type: "string" },
+					status: { type: "string" },
+					jobId: { type: "string" },
+					model: { type: "string" },
+					url: { type: "string" },
+					prompt: { type: "string" },
+					hint: { type: "string" }
+				}
+			},
+			render: (_args, result) => [{
+				type: "text",
+				text: result?.hint || "图片已生成"
+			}]
+		},
+		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 后再试`);
+			let picked = [];
+			try {
+				picked = await getEntries?.() ?? [];
+			} catch {
+				picked = [];
+			}
+			const entries = Array.isArray(picked) ? picked : [];
+			const configuredPreferred = str(settings?.drawModelId, "");
+			const panelPreferred = typeof getPreferredModelId === "function" ? await getPreferredModelId().catch(() => null) : null;
+			const preferred = typeof panelPreferred === "string" && panelPreferred.trim() !== "" ? panelPreferred : configuredPreferred;
+			const model = pickDrawModel(entries, str(params?.model, ""), preferred);
+			if (model === null) throw new Error("目录里没有出图模型（image-to-image / text-to-image 条目为空）：确认令牌已配置、面板已至少轮询一次，且套餐含该模型");
+			const rawImages = splitImageUrls(params?.imageUrl);
+			const images = [];
+			for (const raw of rawImages) {
+				const normalized = normalizeImageUrlInput(raw);
+				if (normalized === null) throw new Error(`imageUrl 不可用：${raw.slice(0, 80)} —— 只接受公网 http(s) 链接或 data:image/...;base64 内联数据（本地文件上游取不到，请先上传）`);
+				images.push(normalized);
+			}
+			try {
+				const size = str(params?.size, "");
+				const steps = toPositiveInt(params?.steps);
+				const guidance = toPositiveNumber(params?.guidance);
+				const seed = toNonNegativeInt(params?.seed);
+				const negativePrompt = str(params?.negativePrompt, "");
+				const { taskId } = await submitDrawTask({
+					fetchImpl,
+					apiBase,
+					apiKey,
+					model,
+					prompt,
+					...images.length > 0 ? { imageUrl: images } : {},
+					...size !== "" ? { size } : {},
+					...steps !== void 0 ? { steps } : {},
+					...guidance !== void 0 ? { guidance } : {},
+					...seed !== void 0 ? { seed } : {},
+					...negativePrompt !== "" ? { negativePrompt } : {}
+				});
+				const job = jobs.create({
+					taskId,
+					model,
+					prompt
+				});
+				return await waitAndReport(apiKey, job, drawModelIds(entries));
+			} catch (error) {
+				cooldown.fail();
+				throw error;
+			}
+		}
+	});
+}
+/**
+* 把工具参数里的输入图拆成列表。
+*
+* 官方支持多图（数组形状），而 agent 工具的参数类型是标量，所以约定**用换行分隔**
+* 多张。同时容忍调用方直接传数组（内部调用与测试会这么用）。
+* @param {unknown} value - 原始参数。
+* @returns {string[]} 拆好的 URL（未归一，调用方逐项过闸）。
+*/
+function splitImageUrls(value) {
+	if (Array.isArray(value)) return value.map((v) => String(v)).filter((v) => v.trim() !== "");
+	const raw = str(value, "");
+	if (raw === "") return [];
+	return raw.split(/\r?\n/).map((v) => v.trim()).filter((v) => v !== "");
+}
+/** 读正整数，非法返回 undefined（不下发无意义参数）。 */
+function toPositiveInt(value) {
+	const n = Number(value);
+	return Number.isFinite(n) && n > 0 ? Math.floor(n) : void 0;
+}
+/** 读非负整数（seed 可为 0）。 */
+function toNonNegativeInt(value) {
+	const n = Number(value);
+	return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+}
+/** 读正浮点（guidance 可为小数）。 */
+function toPositiveNumber(value) {
+	const n = Number(value);
+	return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+/** 读 body 文本，读不到给空串（错误分诊不能因为读 body 失败而失败）。 */
+async function safeText(response) {
+	try {
+		return await response.text();
+	} catch {
+		return "";
+	}
+}
+/** 解析 JSON；读不到就返回 `null`，由调用方按「非终态/无 id」处理。 */
+async function safeJson(response, text) {
+	try {
+		return await response.json();
+	} catch {
+		try {
+			return text === "" ? null : JSON.parse(text);
+		} catch {
+			return null;
+		}
+	}
+}
+/** 可注入的 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}
+*/
+function resetDrawToolNote() {
+	note = null;
+}
+
+//#endregion
+//#region src/host/switch-precedence.ts
+/**
+* 所有 opt-in 开关共用的唯一裁决：「面板保存值 vs 配置默认值」。
+*
+* 规则只有一条：**面板保存值赢，否则配置默认值说了算**。来源标签（`panel` /
+* `config`）随答案一起返回，面板才能说出是谁在管。规则收在一处，是为了让开关
+* 再也无法各自发明一套优先级方言；`test/switch-precedence.test.mjs` 钉死这个
+* 方言，照抄形状的新调用方会被它标成异类。
+*
+* 不服务「纯面板拥有、无配置默认值」的开关——那种没有可裁决的配置默认值，
+* 调用方直接读即可。peer-free，纯函数。
+*
+* @module dsh-connect-modelscope-token-plan/switch-precedence
+*/
+/**
+* Resolve the effective boolean switch: a panel-saved value always wins,
+* otherwise the config default rules.
+* @param {boolean|null} panel - the panel-saved value (`null` = never saved).
+* @param {boolean} config - the patch-declared default.
+* @returns {boolean} the effective switch.
+*/
+function resolveSwitchEnabled(panel, config) {
+	return (panel ?? config) === true;
+}
+/**
+* Resolve the effective string preference (e.g. a draw-model id): a
+* panel-saved value wins, otherwise the config default rules.
+* @param {string|null} panel - the panel-saved value (`null` = never saved).
+* @param {string|undefined} config - the patch-declared default.
+* @returns {string|undefined} the effective preference.
+*/
+function resolveSwitchValue(panel, config) {
+	return panel ?? config;
+}
+/**
+* Where the effective value came from — the panel when it saved one, the
+* config otherwise. Rides with every resolved answer so the panel can name
+* the side in charge.
 * @param {boolean|string|null} panel - the panel-saved value.
 * @returns {"panel"|"config"}
 */
@@ -1720,6 +3371,116 @@ function switchSource(panel) {
 	return panel === null ? "config" : "panel";
 }
 
+//#endregion
+//#region src/host/draw-register.ts
+/**
+* 出图工具的挂载副作用：读开关 → 解析目录 → 注册 agent 工具。
+*
+* 与 `provider-publish.ts` 的分工：那个管「魔搭作为 chat provider 的注册」，本文件
+* 管「给 agent 一个出图工具」。两者是**独立的开关**——回答的是不同问题，合并没有
+* 好处（用户可能想用工具出图但不想把魔搭塞进模型选择器，反之亦然）。
+*
+* 承重约束：**peer 的 tools registry 没有 unregister**。所以
+*  - 注册只在挂载时尝试**一次**，不在任何轮询/路由里重复调用；
+*  - 开关在挂载后翻转，要到下次 Host 启动才生效（面板文案必须说这句，否则用户
+*    会以为开关坏了）；
+*  - 目录变化**不需要**重注册：工具在**调用时**才读目录（`getEntries` 是个函数），
+*    所以一次目录刷新会自然被下一次出图看到。
+*
+* 失败一律降级为「工具缺席」，绝不炸掉插件：tools 服务缺失、peer 加载失败、
+* registry 拒收——三种都由 `draw-tool-state.ts` 记下原因供面板显示。本文件不吞
+* 错误（那会让「工具为什么不在」无从诊断），只把它们翻译成可展示的原因码。
+*
+* 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
+*/
+/**
+* 解析一个可选服务，允许它稍后才注册。
+*
+* 承 sensenova 同名函数的纪律：**重试的是读，不是注册**——工具不能注销，重复注册
+* 比缺席更糟。这里只做有限次立即读取，不做长退避（服务要么已注册，要么这次挂载
+* 就没有）。
+* @param {object} ctx - Host 上下文。
+* @param {string} service - 服务名。
+* @param {() => boolean} isDisposed - 卸载闸。
+* @returns {Promise<object|null>} 服务实例或 `null`。
+*/
+async function resolveService(ctx, service, isDisposed) {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		if (isDisposed()) return null;
+		const found = ctx.get?.(service);
+		if (found !== null && found !== void 0) return found;
+		if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 50));
+	}
+	return null;
+}
+/**
+* 读一次开关，决定是否注册出图工具。
+* @param {object} ctx - Host 上下文。
+* @param {object} wiring - `{ settings, configError, tokenStore, inference, providerStore, publisher, logger }`。
+* @param {object} deps - 测试缝（`loadToolsModule`、`drawFetch`）。
+* @returns {Promise<void>}
+*/
+async function registerDrawTool(ctx, wiring, deps = {}) {
+	const { settings, configError, tokenStore, inference, drawStore, publisher, logger } = wiring;
+	const loggerFor = logger ?? ctx.logger;
+	setDrawToolNote(null);
+	try {
+		if (configError !== null) return;
+		const panelValue = drawStore ? await drawStore.enabled().catch(() => null) : null;
+		if (resolveSwitchEnabled(panelValue, settings.drawEnabled === true) !== true) return;
+		const isDisposed = () => publisher?.isDisposed?.() === true;
+		const tools = await resolveService(ctx, "tools", isDisposed);
+		if (tools === null || typeof tools.register !== "function") {
+			setDrawToolNote("no-tools-service");
+			return;
+		}
+		let defineTool = null;
+		try {
+			const mod = await Promise.resolve(deps.loadToolsModule ? deps.loadToolsModule() : import("@deepseek-ai/dsh-tools"));
+			defineTool = mod?.defineTool ?? mod?.default?.defineTool ?? null;
+		} catch (error) {
+			setDrawToolNote("peer-load-failed");
+			loggerFor?.warn?.(`${name}: draw tool peer module failed to load (${redactSecrets(errMsg(error))}) — the tool is absent`);
+			return;
+		}
+		if (typeof defineTool !== "function") {
+			setDrawToolNote("peer-load-failed");
+			return;
+		}
+		const drawFetch = deps.drawFetch ?? ((url, options) => fetch(url, options));
+		tools.register(defineDrawTool({
+			defineTool,
+			fetchImpl: drawFetch,
+			resolveApiKey: async () => (await tokenStore.resolve()).value,
+			getEntries: async () => {
+				return (await inference.fetchModels().catch(() => null))?.entries ?? [];
+			},
+			getPreferredModelId: async () => {
+				const panelValue = drawStore ? await drawStore.modelId().catch(() => null) : null;
+				return resolveSwitchValue(panelValue, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
+			},
+			settings: {
+				apiBase: settings.apiBase,
+				drawModelId: settings.drawModelId,
+				drawTimeoutMs: settings.drawTimeoutMs,
+				drawWaitMs: settings.drawWaitMs
+			},
+			isDisposed
+		}));
+	} catch (error) {
+		setDrawToolNote("registry-refused");
+		loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets(errMsg(error))}) — the tool is absent`);
+	}
+}
+
 //#endregion
 //#region src/host/publish-core.ts
 /**
@@ -1857,6 +3618,15 @@ function registerProviderPair(llm, built, target, { providerId, displayName }) {
 *
 * The module is loaded once and the factory is read off it once, so a Host
 * whose peers resolve slowly pays that cost one time, not per publish.
+*
+* Only the SUCCESS is memoized. The memoized value used to be the promise
+* itself, which pinned a rejection in the slot for the life of the process:
+* after one failed `import()` every later publish rethrew the same error and
+* the provider could never register again — even after the operator fixed the
+* missing peer, which is exactly the remedy this file's own
+* `describeBuildFailure` prints for `ERR_MODULE_NOT_FOUND`. A recoverable
+* install problem cost a Host restart. Clearing the slot on failure keeps
+* "loaded once" for the happy path and gives the next publish a real retry.
 * @param {() => Promise<object>} loadModule - resolves the adapter module.
 * @param {string} exportName - the factory export to read off the module.
 * @returns {() => Promise<Function>} the memoized factory resolver.
@@ -1864,7 +3634,10 @@ function registerProviderPair(llm, built, target, { providerId, displayName }) {
 function createAdapterFactoryResolver(loadModule, exportName) {
 	let adapterFactoryPromise;
 	return async () => {
-		if (adapterFactoryPromise === void 0) adapterFactoryPromise = Promise.resolve(loadModule()).then((mod) => mod?.[exportName]);
+		if (adapterFactoryPromise === void 0) adapterFactoryPromise = Promise.resolve(loadModule()).then((mod) => mod?.[exportName]).catch((error) => {
+			adapterFactoryPromise = void 0;
+			throw error;
+		});
 		return adapterFactoryPromise;
 	};
 }
@@ -1917,6 +3690,13 @@ function warnBuildFailure(logger, label, described) {
 * fact about the Host — not about the provider — so it is one copy: a Host
 * with no `llm` service gets no registration and a stated reason, never a
 * half-built one.
+*
+* The absence routes through {@link unregister}, not a hand-rolled
+* `release(); registered = false`: `state.built` must go down with it. A
+* stale `built` survives into the NEXT publish as its rollback target, so a
+* later failed publish would re-register an adapter whose release has already
+* been called — a rollback path running against a dead pair, which is the
+* worst possible moment to discover the divergence.
 * @param {object} job
 * @param {object} job.state - the publisher state.
 * @param {(service: string) => object|null} job.getLlm - the service resolver.
@@ -1927,9 +3707,11 @@ function resolveRegistrationService({ state, getLlm, release }) {
 	const llm = getLlm("llm");
 	state.llmAvailable = llm !== null && typeof llm.registerAdapter === "function";
 	if (!state.llmAvailable) {
-		release();
-		state.registered = false;
-		state.error = NO_LLM_SERVICE_ERROR;
+		unregister({
+			state,
+			release,
+			error: NO_LLM_SERVICE_ERROR
+		});
 		return null;
 	}
 	return llm;
@@ -1993,15 +3775,13 @@ function swapRegistration({ llm, built, previousBuilt, state, release, registerP
 		state.built = null;
 		onRollback?.();
 		state.error = redactSecrets(errMsg(error));
-		if (previousBuilt !== null) try {
-			registerPair(llm, previousBuilt, state);
-			state.built = previousBuilt;
-			state.registered = true;
-		} catch {
-			state.built = null;
-			state.registered = false;
-		}
-		else state.registered = false;
+		restorePreviousPair({
+			llm,
+			previousBuilt,
+			state,
+			registerPair,
+			release
+		});
 		return {
 			ok: false,
 			error
@@ -2014,6 +3794,30 @@ function swapRegistration({ llm, built, previousBuilt, state, release, registerP
 	return { ok: true };
 }
 /**
+* 注册失败后恢复先前在服务的 provider 对（如果有）。
+*
+* 从 {@link swapRegistration} 提取，把 catch 块里的嵌套从 4 层降到 2 层——
+* 原实现里 `registerPair(llm, previousBuilt, ...)` 住在 try 内、try 住在
+* catch 内，读起来要数四层缩进才能确认它在做什么。行为完全不变：先摘掉
+* 新对（`release()` 已在调用方做过），再尝试挂回旧对；旧对也注册不上就
+* 诚实地标 `registered: false`。
+*/
+function restorePreviousPair({ llm, previousBuilt, state, registerPair, release }) {
+	if (previousBuilt === null) {
+		state.registered = false;
+		return;
+	}
+	try {
+		registerPair(llm, previousBuilt, state);
+		state.built = previousBuilt;
+		state.registered = true;
+	} catch {
+		release();
+		state.built = null;
+		state.registered = false;
+	}
+}
+/**
 * Emit the adapter-update event, tolerating a Host that has no `emit` and a
 * Host whose `emit` refuses.
 *
@@ -2049,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")`），所以离线套件可以换
@@ -2063,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` 是
@@ -2086,7 +3924,7 @@ function createProviderPublisher(deps = {}) {
 	const { settings, panelSwitch, loadAdapterModule, getLlm, resolveApiKey, usage, emit, logger } = deps;
 	const effectiveSettings = settings ?? {};
 	const effectivePanelSwitch = panelSwitch ?? (async () => null);
-	const effectiveLoadAdapterModule = loadAdapterModule ?? (() => import("./llm-adapter-DnaNNORe.js"));
+	const effectiveLoadAdapterModule = loadAdapterModule ?? (() => import("./llm-adapter.js"));
 	const effectiveGetLlm = getLlm ?? (() => null);
 	const effectiveResolveApiKey = resolveApiKey ?? (async () => "");
 	const effectiveLogger = logger ?? { warn: () => {} };
@@ -2134,20 +3972,46 @@ function createProviderPublisher(deps = {}) {
 		displayName: LLM_DISPLAY_NAME
 	});
 	/**
-	* 为一个目录/允许清单快照（重）构建并注册 provider。
+	* 空转守卫的公共判据：目录 offer 与额度耗尽集合是否都没变。
 	*
-	* 重建并重注册而非原地改：`PiAiAdapter` 内部 memoize profiles 快照，只有新的注册
-	* 才能改变提供的模型列表。注册失败时**恢复上一对**，所以坏 publish 永远不能把
-	* 已在服务的模型拉下来。
-	* @param {object[]} entries - 归一目录条目。
-	* @param {string[]} enabledIds - 允许清单（空 = 全部）。
-	* @param {string[]} [unavailableModelIds] - 要从 picker 的 offer 里丢掉的额度耗尽 id。
-	* @returns {Promise<{ok: boolean, skipped?: boolean, error?: unknown}>}
+	* 两处空转守卫（开关关着 / 开关开着）共用这个签名比对——公式与轮询同源
+	* （由 {@link syncSignaturesAfterPublish} 内部调用导出的 {@link catalogSignature}
+	* 与 {@link quotaSignatureOf}），不会漂移。提取成函数避免两处各写一遍。
+	* @returns {boolean} true = offer 没变，可以跳过这次 publish。
 	*/
-	const publishProviderOnce = async (entries, enabledIds, unavailableModelIds = []) => {
-		if (queue.isDisposed()) return {
-			ok: false,
-			skipped: true
+	const offerUnchanged = () => state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds);
+	/**
+	* 发布相位——两道空转守卫的判断条件从此有名字（推导见 {@link publisherPhaseOf}）。
+	* @param {boolean} disposed - 当前是否已 dispose。
+	* @returns {PublisherPhase}
+	*/
+	const phaseOf = (disposed) => publisherPhaseOf(state, disposed);
+	/**
+	* gather 阶段：一次 publish 的**可挂起**半边。
+	*
+	* 读面板开关、解析 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 gatherPublish = async (entries, enabledIds, unavailableModelIds) => {
+		if (queue.isDisposed()) return {
+			kind: "done",
+			result: {
+				ok: false,
+				skipped: true
+			}
 		};
 		const previousBuilt = state.built;
 		const previousEntries = state.entries;
@@ -2158,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 && state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds)) 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,
@@ -2175,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,
@@ -2198,36 +4070,98 @@ 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 && state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds)) 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);
+		if (result.ok === false && state.registered === true && state.signature === requestedSignature) state.error = null;
 		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 开关、
@@ -2301,11 +4235,134 @@ 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
 /**
 * 路由字面量。浏览器 bundle（src/client/const.ts）无法从 host-config 导入，
-* 两边各写一份字面量——由 test/config.test.mjs 钉住相等，改名时先红再改。
+* 两边各写一份字面量——由 test/panel.test.mjs 的 §6/§6b 钉住两端解析出的完整
+* 路径集合双向相等，改名时先红再改。（原注释指向 test/config.test.mjs，但那套
+* 钉的是 CONFIG_DEFAULTS ↔ cordis.patch.yml，不含路由字面量。）
 * @module dsh-connect-modelscope-token-plan/routes/paths
 */
 const SNAPSHOT_PATH = "/api/dsh-connect-modelscope-token-plan/snapshot";
@@ -2314,6 +4371,7 @@ const TOKEN_PATH = "/api/dsh-connect-modelscope-token-plan/token";
 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";
 
 //#endregion
 //#region src/host/snapshot-aggregate.ts
@@ -2357,61 +4415,47 @@ async function soft(promise) {
 		};
 	}
 }
-/**
-* Provider 状态块降级形状：读不到开关/注册状态/目录时，面板仍然得到一个完整
-* 可渲染的块（开关关、roster 空、error 说明原因），绝不让整条快照失败。
-*/
-function providerDegraded(error) {
-	return {
-		enabled: false,
-		source: "config",
-		llmAvailable: false,
-		registered: false,
-		error,
-		modelCount: 0,
-		enabledCount: 0,
-		allowed: "all",
-		enabledIds: [],
-		roster: []
-	};
-}
 /** 聚合快照 body。wiring 子集见 routes/snapshot.ts 的 Pick。 */
 async function buildSnapshotBody(wiring) {
-	const { settings, tokenStore, usageStore, inference, providerStore, publisher } = wiring;
-	const [tokenState, daily, perModel, trend, events] = await Promise.all([
+	const { settings, tokenStore, usageStore, inference, providerStore, drawStore, publisher } = wiring;
+	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.events())
+		soft(usageStore.events()),
+		soft(providerStore.versionNote())
 	]);
 	const shapeWarnings = [];
 	const usageAnomaly = usageStore.anomaly();
 	if (usageAnomaly !== null) shapeWarnings.push(usageAnomaly);
-	for (const path of [
-		tokenState,
-		daily,
-		perModel,
-		trend,
-		events
-	]) if (!path.ok) shapeWarnings.push(`usage-source failed (${path.code}): ${path.error}`);
-	const tokenPresent = tokenState.ok ? tokenState.value.present : false;
-	const balance = await soft(inference.fetchBalance());
-	const models = await soft(inference.fetchModels());
+	for (const [label, path] of [
+		["token", tokenState],
+		["daily", daily],
+		["per-model", perModel],
+		["trend", trend],
+		["events", events]
+	]) if (!path.ok) shapeWarnings.push(`${label} source failed (${path.code}): ${path.error}`);
+	const tokenKnownAbsent = tokenState.ok && tokenState.value.present === false;
+	const contextOverride = await providerStore.contextWindow().catch(() => null);
+	const [balance, models] = await Promise.all([soft(inference.fetchBalance()), soft(inference.fetchModels(contextOverride))]);
 	const modelIds = models.ok ? models.value.ids : [];
 	const modelEntries = models.ok ? models.value.entries : [];
 	if (!models.ok && models.code !== "network_error") shapeWarnings.push(`models: ${models.error}`);
-	if (tokenPresent && !balance.ok && balance.code !== "network_error") shapeWarnings.push(`balance: ${balance.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);
 		const source = switchSource(panel);
 		const roster = rosterWithAvailability(modelEntries, []);
 		const stored = await providerStore.enabledIds().catch(() => null);
-		const enabledIds = Array.isArray(stored) ? stored : Array.isArray(publisher.state.enabledIds) ? publisher.state.enabledIds : [];
-		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;
+		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);
 		return {
 			enabled,
 			source,
@@ -2420,12 +4464,31 @@ 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
 		};
 	})());
-	const usedLocal = daily.ok ? daily.value.calls : 0;
+	const draw = await soft((async () => {
+		const panel = await drawStore.enabled().catch(() => null);
+		const panelModel = await drawStore.modelId().catch(() => null);
+		const candidateIds = imageGenModelIds(modelEntries);
+		return {
+			enabled: resolveSwitchEnabled(panel, settings.drawEnabled),
+			source: switchSource(panel),
+			candidateIds,
+			candidateCount: candidateIds.length,
+			preferredModel: resolveSwitchValue(panelModel, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null,
+			preferredSource: switchSource(panelModel),
+			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,
 		name,
@@ -2433,12 +4496,16 @@ async function buildSnapshotBody(wiring) {
 		now: (/* @__PURE__ */ new Date()).toISOString(),
 		pollSeconds: settings.pollSeconds,
 		cacheSeconds: settings.cacheSeconds,
-		token: tokenState.ok ? tokenState.value : {
+		token: tokenState.ok ? {
+			...tokenState.value,
+			readError: null
+		} : {
 			present: false,
 			source: "none",
 			valid: null,
 			checkedAt: null,
-			ephemeral: true
+			ephemeral: true,
+			readError: tokenState.error
 		},
 		balance: balance.ok ? {
 			available: balance.value.available,
@@ -2451,7 +4518,7 @@ async function buildSnapshotBody(wiring) {
 			total: null,
 			frozen: null,
 			fetchedAt: null,
-			error: tokenPresent ? balance.error : null
+			error: tokenKnownAbsent ? null : balance.error
 		},
 		quota: {
 			daily: { usedLocal },
@@ -2469,7 +4536,8 @@ 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
 	};
@@ -2570,6 +4638,22 @@ function redactedError(error) {
 	const text = redactSecrets(errMsg(error));
 	return text.trim() === "" ? "request failed" : text;
 }
+/**
+* 写盘/操作失败的统一响应：HTTP 恒 200、成败看 body（与快照路由同一语义，
+* 一次写失败不许顺着渲染树炸穿）。**用户显式操作的失败必须上屏**，所以
+* 调用方不吞、这里只负责脱敏后的标准形状。provider 开关/清单/reset 与
+* token save/forget 五处 catch 曾各写一遍这个 writeJson——集中成一份，
+* 措辞与形状不会漂移。
+* @param {object} response - webServer 的响应对象。
+* @param {unknown} error - catch 到的任意值（未必是 Error）。
+* @returns {void}
+*/
+function respondError(response, error) {
+	writeJson(response, 200, {
+		ok: false,
+		error: redactedError(error)
+	}, { "cache-control": "no-store" });
+}
 /** 读并校验 JSON body，失败时写 400 并返回 null（调用方的停手信号）。 */
 async function readJsonBodyOr400(request, response, limit = MAX_JSON_BODY_BYTES) {
 	const body = await readJsonBody(request, limit);
@@ -2702,7 +4786,14 @@ function registerModelsRoute(ctx, wiring) {
 * 简化（SPIKE.md §结论 3）。
 * @module dsh-connect-modelscope-token-plan/routes/token
 */
-/** 注册令牌路由（POST /token 保存，POST /token/forget 忘掉）。 */
+/**
+* 注册令牌路由（POST /token 保存，POST /token/forget 忘掉）。
+*
+* 返回类型是本族唯一的一个**数组**：token 注册两条路由（save + forget），其余
+* 路由族各只注册一条、返回单个 off()。标注在**这里**而不是在 routes.ts 里对
+* 调用结果做 `as Array<() => void>` 断言——断言放在消费端等于把「这两条返回的是
+* 注销回调而不是 handler」这个约定藏起来，标注在产地才是声明。
+*/
 function registerTokenRoute(ctx, wiring) {
 	const { settings, tokenStore } = wiring;
 	const save = withOrigin(async (request, response) => {
@@ -2727,10 +4818,7 @@ function registerTokenRoute(ctx, wiring) {
 				...await tokenStore.state()
 			}, { "cache-control": "no-store" });
 		} catch (error) {
-			writeJson(response, 200, {
-				ok: false,
-				error: redactedError(error)
-			}, { "cache-control": "no-store" });
+			respondError(response, error);
 		}
 	}, settings.allowedHosts);
 	const forget = withOrigin(async (request, response) => {
@@ -2745,10 +4833,7 @@ function registerTokenRoute(ctx, wiring) {
 				...await tokenStore.state()
 			}, { "cache-control": "no-store" });
 		} catch (error) {
-			writeJson(response, 200, {
-				ok: false,
-				error: redactedError(error)
-			}, { "cache-control": "no-store" });
+			respondError(response, error);
 		}
 	}, settings.allowedHosts);
 	return [ctx.webServer.register({
@@ -2807,13 +4892,15 @@ function registerProbeRoute(ctx, wiring) {
 			}
 			try {
 				const result = await inference.probe({ modelId });
+				wiring.tokenStore.noteValidity(true);
 				writeJson(response, 200, {
 					...result,
-					tokenState: await wiring.tokenStore.state()
+					tokenState: await wiring.tokenStore.state().catch(() => null)
 				}, { "cache-control": "no-store" });
 			} catch (error) {
 				const code = error.code;
 				const message = redactedError(error);
+				if (code === CODE.AUTH_ERROR) wiring.tokenStore.noteValidity(false);
 				const eventKind = code === CODE.QUOTA_EXCEEDED ? "quota" : code === CODE.RATE_LIMITED ? "rate_limit" : "error";
 				await usageStore.recordEvent({
 					modelId,
@@ -2837,13 +4924,15 @@ function registerProbeRoute(ctx, wiring) {
 //#endregion
 //#region src/host/routes/provider.ts
 /**
-* provider 注册路由：开关读/写、允许清单保存、回退默认。
+* provider 注册路由：开关读/写、允许清单保存、上下文窗口覆盖、回退默认。
 *
-* 三件事（§9）：
-*   - GET  `PROVIDER_PATH`        读当前开关 + 目录 + 允许清单 + 注册状态（无副作用）；
-*   - POST `PROVIDER_PATH`        body `{enabled?: boolean}` → 保存面板开关并重注册；
-*   - POST `PROVIDER_PATH/roster` body `{enabledIds?: string[]}` → 保存允许清单并重注册；
-*   - POST `PROVIDER_PATH/reset`  忘掉面板开关与允许清单，回到 patch 默认。
+* 四件事（§9）：
+*   - GET  `PROVIDER_PATH`           读当前开关 + 目录 + 允许清单 + 注册状态（无副作用）；
+*   - POST `PROVIDER_PATH`           body `{enabled?: boolean}` → 保存面板开关并重注册；
+*   - POST `PROVIDER_PATH/roster`    body `{enabledIds?: string[]}` → 保存允许清单并重注册；
+*   - POST `PROVIDER_PATH/context`   body `{contextWindow: number|null}` → 保存全局上下文
+*     窗口覆盖并重注册（null = 跟随目录）；
+*   - POST `PROVIDER_PATH/reset`     忘掉面板开关、允许清单与窗口覆盖，回到 patch 默认。
 *
 * `withOrigin` 围栏与 `refuseMethod` 照现有路由；写开关/清单失败**必须传播**
 * （`ok:false` + error），不静默吞——这是用户的显式操作，面板必须看见它没生效。
@@ -2853,9 +4942,16 @@ function registerProbeRoute(ctx, wiring) {
 */
 /**
 * 读目录条目，读不到按空目录降级（GET 不能因目录失败把整个面板状态打掉）。
+*
+* 读目录前先取**当前窗口覆盖**传给 `fetchModels`：条目在归一前打上覆盖标记，
+* descriptor / roster / catalogSignature 都从这份条目派生。每个写路由（开关、
+* 清单、窗口、reset）都经这里取条目再 publish，所以任何一次重注册都带着最新
+* 覆盖——否则先存窗口、再存清单会把未打标的目录重新注册上去，覆盖静默失效到
+* 下一轮轮询。
 */
-async function readEntries(inference) {
-	const catalog = await inference.fetchModels().catch((error) => {
+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
@@ -2865,25 +4961,20 @@ async function readEntries(inference) {
 }
 /**
 * 读「当前」允许清单：优先持久化的，否则 publisher 最近 publish 的那份。
+*
+* 判据是**共用**的 resolveEnabledIds（provider-store）——本文件与面板聚合、
+* index.ts 的轮询必须对「空清单」给同一个答案，否则三个界面各说一套。
 */
 async function readEnabledIds(store, published) {
-	const stored = await optional(store.enabledIds?.(), null);
-	if (Array.isArray(stored)) return stored;
-	return Array.isArray(published) ? 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。
@@ -2892,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 共用，所以两个方向不可能对「当前
 	* 状态是什么」说两套话。
@@ -2902,11 +4993,11 @@ function registerProviderRoute(ctx, wiring) {
 	const snapshot = async (extra = {}) => {
 		const panelSwitch = await optional(providerStore.enabled());
 		const enabledIds = await readEnabledIds(providerStore, publisher.state.enabledIds);
-		const entries = await readEntries(inference);
+		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),
@@ -2915,9 +5006,10 @@ 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,
 			...extra
 		};
@@ -2947,13 +5039,9 @@ function registerProviderRoute(ctx, wiring) {
 			}
 			try {
 				await providerStore.save(body.enabled);
-				const entries = await readEntries(inference);
-				await publisher.publish(entries, await readEnabledIds(providerStore, publisher.state.enabledIds), []);
+				await reconcile();
 			} catch (error) {
-				writeJson(response, 200, {
-					ok: false,
-					error: redactedError(error)
-				}, { "cache-control": "no-store" });
+				respondError(response, error);
 				return;
 			}
 			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
@@ -2979,15 +5067,38 @@ function registerProviderRoute(ctx, wiring) {
 			const ids = body.enabledIds.filter((id) => typeof id === "string" && id !== "");
 			try {
 				await providerStore.saveEnabledIds?.(ids);
-				const entries = await readEntries(inference);
-				await publisher.publish(entries, ids, []);
+				await reconcile();
 			} catch (error) {
-				writeJson(response, 200, {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	}));
+	offs.push(ctx.webServer.register({
+		kind: "exact",
+		path: `${PROVIDER_PATH}/context`,
+		handler: withOrigin(async (request, response) => {
+			if ((request.method === void 0 ? "POST" : request.method) !== "POST") {
+				refuseMethod(response);
+				return;
+			}
+			const body = await readJsonBodyOr400(request, response);
+			if (body === null) return;
+			if (body.contextWindow !== null && (typeof body.contextWindow !== "number" || !Number.isFinite(body.contextWindow) || body.contextWindow <= 0)) {
+				writeJson(response, 400, {
 					ok: false,
-					error: redactedError(error)
+					error: "expected { contextWindow: number | null }"
 				}, { "cache-control": "no-store" });
 				return;
 			}
+			try {
+				await providerStore.saveContextWindow?.(body.contextWindow);
+				await reconcile();
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
 			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
@@ -3006,15 +5117,165 @@ function registerProviderRoute(ctx, wiring) {
 			try {
 				await providerStore.forget();
 				await providerStore.saveEnabledIds?.([]);
-				const entries = await readEntries(inference);
-				await publisher.publish(entries, [], []);
+				await reconcile();
 			} catch (error) {
-				writeJson(response, 200, {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	}));
+	return () => {
+		for (const off of offs) try {
+			off();
+		} catch (error) {
+			logger?.warn?.(`provider route unregister failed: ${redactedError(error)}`);
+		}
+	};
+}
+
+//#endregion
+//#region src/host/routes/draw.ts
+/**
+* 出图工具路由：开关读/写、模型偏好保存、回到默认。
+*
+* 三条路径：
+*   - GET  `DRAW_PATH`        读开关 + 出图候选模型 + 工具挂载状态（无副作用）；
+*   - POST `DRAW_PATH`        body `{enabled?: boolean, modelId?: string|null}` → 保存；
+*   - POST `DRAW_PATH/reset`  忘掉面板值，回到 patch 默认。
+*
+* **与 provider 路由刻意分开**：provider 管「魔搭作为 chat provider」，本路由管
+* 「给 agent 一个出图工具」。两者的开关、状态文件、候选集合都不同，合并会让
+* 「关掉出图」波及 provider 的注册时序（详见 draw-store.ts 的头注）。
+*
+* 一处**与 provider 路由不同**的地方必须说清：provider 开关翻转会**立即**重注册
+* （publish 是活的重建），而出图工具的开关翻转**要等下次 Host 启动**——peer 的
+* tools registry 没有 unregister，工具一旦注册就摘不下来。所以本路由保存成功后
+* 不改挂载状态，只在响应里给出 `mountPending`，让面板能说清这件事，而不是让用户
+* 以为开关坏了。
+*
+* peer-free：不 import 任何 Host peer。
+* @module dsh-connect-modelscope-token-plan/routes/draw
+*/
+/**
+* 读目录条目，读不到按空目录降级。
+*
+* 与 provider 路由同一条纪律：GET 不能因为一次目录失败就把整个面板状态打掉——
+* 出图候选为空只影响「能不能挑模型」，不影响开关的显示。
+* @param {object} inference - inference client。
+* @returns {Promise<unknown[]>} 归一目录条目。
+*/
+async function readEntries(inference) {
+	const catalog = await inference.fetchModels().catch(() => ({ entries: [] }));
+	return Array.isArray(catalog?.entries) ? catalog.entries : [];
+}
+/**
+* 注册出图路由（两条路径）。
+* @param ctx - host 根上下文（只用 `ctx.webServer`）。
+* @param {DrawRouteWiring} wiring - 本路由读到的子集。
+* @returns {Function} 注销回调。
+*/
+function registerDrawRoute(ctx, wiring) {
+	const { settings, drawStore, inference, logger } = wiring;
+	/**
+	* 组装响应。GET 与写成功后的响应共用，两个方向不可能对「当前状态」说两套话。
+	* @param {object} [extra] - 追加/覆盖字段。
+	* @returns {Promise<object>} 响应体。
+	*/
+	const snapshot = async (extra = {}) => {
+		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;
+		return {
+			ok: true,
+			enabled: resolveSwitchEnabled(panelSwitch, settings.drawEnabled),
+			source: switchSource(panelSwitch),
+			candidateIds,
+			candidateCount: candidateIds.length,
+			preferredModel: effectiveModelId,
+			preferredSource: switchSource(panelModelId),
+			absentReason: drawToolNote(),
+			/**
+			* 开关的保存**不会**改变本次挂载的工具。
+			*
+			* 工具无法注销（peer 的 tools registry 没有 unregister），所以开关翻转只在
+			* 下次 Host 启动时生效。面板据此显示一句说明——否则用户会以为开关坏了。
+			* 判据：开关为开且本次挂载尚未注册成功（或缺席原因未知）。
+			*/
+			mountPending: resolveSwitchEnabled(panelSwitch, settings.drawEnabled) === true && drawToolNote() !== null,
+			toolName: "modelscope_draw_image",
+			...extra
+		};
+	};
+	const offs = [];
+	offs.push(ctx.webServer.register({
+		kind: "exact",
+		path: DRAW_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 hasEnabled = typeof body.enabled === "boolean";
+			const hasModel = body.modelId === null || typeof body.modelId === "string";
+			if (!hasEnabled && !hasModel) {
+				writeJson(response, 400, {
 					ok: false,
-					error: redactedError(error)
+					error: "expected { enabled?: boolean, modelId?: string|null }"
+				}, { "cache-control": "no-store" });
+				return;
+			}
+			if (body.enabled !== void 0 && !hasEnabled) {
+				writeJson(response, 400, {
+					ok: false,
+					error: "enabled must be a boolean"
+				}, { "cache-control": "no-store" });
+				return;
+			}
+			if (body.modelId !== void 0 && !hasModel) {
+				writeJson(response, 400, {
+					ok: false,
+					error: "modelId must be a string or null"
 				}, { "cache-control": "no-store" });
 				return;
 			}
+			try {
+				if (hasEnabled) await drawStore.saveEnabled(body.enabled);
+				if (body.modelId !== void 0) await drawStore.saveModelId(body.modelId);
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	}));
+	offs.push(ctx.webServer.register({
+		kind: "exact",
+		path: `${DRAW_PATH}/reset`,
+		handler: withOrigin(async (request, response) => {
+			if ((request.method === void 0 ? "POST" : request.method) !== "POST") {
+				refuseMethod(response);
+				return;
+			}
+			await readJsonBody(request, MAX_JSON_BODY_BYTES).catch(() => ({
+				ok: false,
+				error: "ignored"
+			}));
+			try {
+				await drawStore.reset();
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
 			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
@@ -3022,7 +5283,7 @@ function registerProviderRoute(ctx, wiring) {
 		for (const off of offs) try {
 			off();
 		} catch (error) {
-			logger?.warn?.(`provider route unregister failed: ${redactedError(error)}`);
+			logger?.warn?.(`draw route unregister failed: ${redactedError(error)}`);
 		}
 	};
 }
@@ -3042,7 +5303,8 @@ function registerRoutes(ctx, wiring) {
 		registerModelsRoute(ctx, wiring),
 		...registerTokenRoute(ctx, wiring),
 		registerProbeRoute(ctx, wiring),
-		registerProviderRoute(ctx, wiring)
+		registerProviderRoute(ctx, wiring),
+		registerDrawRoute(ctx, wiring)
 	];
 }
 
@@ -3051,8 +5313,12 @@ function registerRoutes(ctx, wiring) {
 /**
 * dsh-connect-modelscope-token-plan — Host 半边（thin router）。
 *
-* 读魔搭 API-Inference 的**本地用量**（上游没有余额接口，见 docs/SPIKE.md）
-* 并经一条只读 /api 路由喂给 Client 面板。重活都在专注的兄弟模块里，本文件
+* 读魔搭 API-Inference 的**本地用量**，并把它与官方魔粒余额一起经一条只读 /api
+* 路由喂给 Client 面板。口径分工：推理响应**不携带**额度头（SPIKE.md §结论 1），但
+* 官方另有魔粒余额端点（`GET {siteBase}/openapi/v1/magicubes/balance`，SPIKE.md
+* 文首后记，2026-10-04 实测可用），面板头条读的是它；本文件下的兄弟模块只负责本地
+* 计数那一半（按模型分布 / 本地趋势 / 429 事件流），回答官方余额答不了的问题。
+* 重活都在专注的兄弟模块里，本文件
 * 只保留 Cordis 入口（name/inject/apply）、wiring 装配与卸载副作用：
 *
 *   - `host-config.ts`        配置契约 + isAdmitted 信任围栏
@@ -3072,11 +5338,16 @@ function registerRoutes(ctx, wiring) {
 * @param ctx - Host 根上下文。
 * @param config - 行的原始 patch 配置（无 schema，未校验；坏配置以
 *   configError 经快照呈现，而不是在挂载时炸掉整台插件）。
-* @param deps - 测试缝（fetchImpl）。真实 Loader 不传。
+* @param deps - 测试缝（`HostDeps`：fetchImpl / getLlm / emit / credentials / env
+*   与出图那两条）。真实 Loader 不传；**每个缝不传时都必须落回 ctx 或全局默认**，
+*   产品行为零漂移。声明与接线由 `test/deps-wiring.test.mjs` 双向扫描守着。
 */
 function apply(ctx, config = {}, deps = {}) {
 	const { settings, configError } = resolveSettings(config);
-	const tokenStore = createTokenStore({ credentials: () => ctx.get("credentials") ?? null });
+	const tokenStore = createTokenStore({
+		credentials: deps.credentials !== void 0 ? deps.credentials : () => ctx.get("credentials") ?? null,
+		env: deps.env
+	});
 	const profile = profileSegment(ctx);
 	const usageStore = createFileUsageStore({
 		name,
@@ -3095,10 +5366,14 @@ function apply(ctx, config = {}, deps = {}) {
 		profile,
 		logger: ctx.logger
 	});
+	const drawStore = createFileDrawStore({
+		profile,
+		logger: ctx.logger
+	});
 	const publisher = createProviderPublisher({
 		settings,
 		panelSwitch: () => providerStore.enabled(),
-		getLlm: (service) => ctx.get?.(service) ?? null,
+		getLlm: deps.getLlm ?? ((service) => ctx.get?.(service) ?? null),
 		resolveApiKey: async () => (await tokenStore.resolve()).value,
 		usage: {
 			recordCall: (input) => usageStore.recordCall({
@@ -3107,25 +5382,17 @@ function apply(ctx, config = {}, deps = {}) {
 			}).catch(() => {}),
 			recordEvent: (input) => usageStore.recordEvent(input).catch(() => {})
 		},
-		emit: (event) => ctx.emit?.(event),
+		emit: deps.emit ?? ((event) => ctx.emit?.(event)),
+		...deps.loadAdapterModule ? { loadAdapterModule: deps.loadAdapterModule } : {},
+		logger: ctx.logger
+	});
+	const { reconcile } = createProviderReconciler({
+		settings,
+		providerStore,
+		inference,
+		publisher,
 		logger: ctx.logger
 	});
-	/**
-	* 一次目录轮询：拉目录 + 读落盘允许清单，再 publish 当前 offer。
-	*
-	* 允许清单必须走 `providerStore.enabledIds()`——清单是**落盘**的（provider-store
-	* 按 profile 分段持久化），重启后内存里的 `publisher.state.enabledIds` 早已清空，
-	* 若从它读，用户勾选的清单会随重启静默丢失（见 fix A）。
-	* @returns {Promise<void>}
-	*/
-	const runPoll = async () => {
-		try {
-			const catalog = await inference.fetchModels();
-			const stored = await providerStore.enabledIds().catch(() => null);
-			const enabledIds = Array.isArray(stored) && stored.length > 0 ? stored : Array.isArray(publisher.state.enabledIds) ? publisher.state.enabledIds : [];
-			await publisher.publish(catalog.entries, enabledIds, []);
-		} catch {}
-	};
 	const wiring = {
 		settings,
 		configError,
@@ -3133,17 +5400,21 @@ function apply(ctx, config = {}, deps = {}) {
 		usageStore,
 		inference,
 		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);
+			resetDrawToolNote();
 			publisher.dispose();
 			publisher.release();
 			for (const off of offs) try {