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

package/lib/index.js

@@ -261,6 +261,10 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 *    现在三件套各有一份公共实现：串行化是{@link createStateWriteQueue}、写守卫是
 *    {@link guardStateWrite}、读侧说明是{@link stateVersionNote}；provider /
 *    usage / draw 三个 store 都是调用方，不再各写一遍。
+* 4. 第四步删掉了{@link createStateReadCache} 的 `inheritFrom`——一个从未被
+*    任何 store 使用、且写回路径绕过写队列的迁移缝（死代码 + 有害形状 +
+*    文档误导三合一，裁定见该函数的说明）；同时把{@link writeStateFile} 的
+*    临时文件清理从「rename 失败」一条路扩大到**任何**失败路径。
 *
 * @module dsh-connect-modelscope-token-plan/state-store
 */
@@ -436,14 +440,17 @@ function temporaryOf(dir, base, now = Date.now) {
 * 载荷串以换行结尾，与本模块存在前每个 store 的写法一致。失败**向上传播** ——
 * 调用方自己决定只读 Home 要不要吞（throttle/catalog 吞，provider 开关不吞）。
 *
-* ## rename 失败时的临时文件清理
+* ## 任何一步失败都要清掉临时文件
 *
 * `rename` 会失败，而最常见的原因是 Windows 上目标文件正被另一个进程/编辑器
 * 占着（EACCES/EPERM）。临时文件此前**留在原地**：名字是
 * `<base>.<pid>.<ts>.<uuid>.tmp`，每次失败多一个，于是
 * `state/<profile>/<name>/` 慢慢堆满垃圾，而没有任何代码会去清它们（全仓原本
-* 无任何 unlink）。现在失败时删掉自己的临时文件再重抛——清理失败不掩盖原始错误
-* （那才是调用方要处理的），所以只 `catch {}`。
+* 无任何 unlink）。第一次修只补了 rename 失败那一条路；`writeFile` 本身失败
+* （磁盘满）、`open` 失败、`handle.sync()` 失败（EIO）留下的半截临时文件照样
+* 堆——2026-10-18 改为：**try 覆盖到 rename 成功为止，catch 里删掉自己的临时
+* 文件再重抛**。清理失败不掩盖原始错误（那才是调用方要处理的），所以只
+* `catch {}`。
 *
 * @param {string} file - 最终文件路径。
 * @param {string} payload - 序列化后的正文（JSON 文本）。
@@ -451,17 +458,17 @@ function temporaryOf(dir, base, now = Date.now) {
 * @returns {Promise<void>}
 */
 async function writeStateFile(file, payload, { temporary }) {
-	await writeFile(temporary, `${payload}\n`, {
-		encoding: "utf8",
-		mode: 384
-	});
-	const handle = await open(temporary, "r+");
-	try {
-		await handle.sync();
-	} finally {
-		await handle.close();
-	}
 	try {
+		await writeFile(temporary, `${payload}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+		const handle = await open(temporary, "r+");
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
 		await rename(temporary, file);
 	} catch (error) {
 		try {
@@ -496,54 +503,40 @@ const STATE_READ_TTL_MS = 1e3;
 * peer-free，与其余原语同纪律（不 import Host peer、离线可测）。时钟与 TTL
 * 都可注入，便于测试把缓存推进过期。
 *
-* `inheritFrom` 是一次性迁移缝：按 profile 分段后，本 profile 的新文件
-* 一开始并不存在，而旧版把值放在**所有 profile 共享**的目录里。给了它以后，
-* 读穿透发现自己的记录缺失时会去旧路径取一次、回填、再返回——**只尝试一次**
-* （`adopted` 标志），所以它不会变成每个 TTL 周期都多读一个文件。
-*
-* 为什么让缓存原语承担这件事，而不是在外面先跑一遍迁移脚本：迁移就有了时序，
-* 而"先迁移、再 seed"在 `apply()` 的同步构造里排不出确定顺序。挂在读穿透上
-* 则天然正确——任何读到"空"的地方都会自动拿到旧值，且与并发进程无关（读到
-* 同一份旧值、写同一份结果）。
+* ## 这个原语为什么不负责 legacy 继承
+*
+* 一次性迁移缝（profile 分段前写在**共享**目录里的状态 → 本 profile 目录）曾经
+* 作为 `inheritFrom` 选项住在这里，2026-10-18 删除，三个原因叠在一起：
+*   - **死代码**：四个 store 无一带它（`grep -rn inheritFrom src/` 只命中本文件
+*     自己的声明；实际继承是 provider-store 在读穿透闭包里手写的）；
+*   - **有害形状**：它的写回是**读路径内直接触发的写**，不经本 store 的写队列
+*     ——那正是 provider-store 注释里记着「咬过三次」的竞态形状：继承写与并发
+*     的用户保存竞争，而继承只发生一次，被盖掉的那次保存是**永久**丢失的；
+*   - **文档误导**：本文件与 provider-store 的注释都把继承描述成走这个缝，
+*     实为两处手写，读者会以为它是共享基础设施。
+* 现在 provider / usage-prefs 各自在读穿透闭包里手写继承，并把回填排进**自己
+* 的写队列**（裁定在各自头注）。新 store 要继承时照那个形状写，**不要**复活
+* 这个参数。
 *
 * @template T
 * @param {() => Promise<T|null>} readThrough - 真正的读盘 + 解析；返回 `null` 表示无可用记录。
 * @param {object} [options]
 * @param {number} [options.ttlMs] - 缓存有效期，默认 {@link STATE_READ_TTL_MS}。
 * @param {() => number} [options.now] - 时钟源；测试注入。
-* @param {{read: () => Promise<T|null>, write: (value: T) => Promise<void>}|null} [options.inheritFrom]
-*   - 旧版共享布局（`read`）与把它回填到本 profile（`write`）；`null` = 不迁移。
 * @returns {{read: () => Promise<T|null>, remember: (value: T|null) => void}}
 */
 function createStateReadCache(readThrough, options = {}) {
-	const { ttlMs = STATE_READ_TTL_MS, now = Date.now, inheritFrom = null } = options;
+	const { ttlMs = STATE_READ_TTL_MS, now = Date.now } = options;
 	let cached = void 0;
 	let cachedAt = 0;
-	/** Whether the one-shot legacy adoption has already been attempted. */
-	let adopted = false;
-	/**
-	* 读穿透：自己的记录优先；缺失且还有旧布局可继承时，取一次旧值并回填。
-	* @returns {Promise<T|null>}
-	*/
-	const load = async () => {
-		const own = await readThrough();
-		if (own !== null || inheritFrom === null || adopted) return own;
-		adopted = true;
-		const inherited = await inheritFrom.read();
-		if (inherited === null) return null;
-		try {
-			await inheritFrom.write(inherited);
-		} catch {}
-		return inherited;
-	};
 	return {
 		/**
-		* 读值：TTL 内返回缓存，过期则穿透到 `load()`。
+		* 读值：TTL 内返回缓存，过期则穿透到 `readThrough()`。
 		* @returns {Promise<T|null>}
 		*/
 		async read() {
 			if (cached !== void 0 && now() - cachedAt < ttlMs) return cached;
-			cached = await load();
+			cached = await readThrough();
 			cachedAt = now();
 			return cached;
 		},
@@ -883,6 +876,14 @@ function parseRetryAfterMs(headers, message) {
 * + rename）、损坏即忽略、版本守卫拒覆写未知版本。进程内 1s 读缓存让一次
 * 快照聚合的多次问询自洽。
 *
+* 旧共享布局**不继承**（2026-10-18 补记的裱定）：profile 分段前写在共享目录里的
+* usage.json 不做一次性迁移——它回答「这个 profile 的调用吃了多少额度」，而无
+* profile 时期（宿主不提供 profileContext）的账不属于任何一个 profile，整段搬
+* 过来是把那段账算成这个 profile 的。宿主升级后开始提供该服务时，旧文件原地
+* 保留，由 `npm run doctor` 以 shared (legacy) 作用域报出——面板不搬历史，但操作者看得见
+* 它（诊断诚实性，见 doctor.ts）。（usage-prefs 的单值偏好反而继承，裱定见
+* usage-prefs-store.ts 头注）。
+*
 * 语义基线（wire.ts）：
 * - 天桶缺失 = 该日本插件没有记录到调用 = 真实的 0，不是数据丢失；
 * - models 的 `tokens` 可为 null（上游没给 usage 时），绝不把 null 写成 0；
@@ -1056,7 +1057,19 @@ function createFileUsageStore({ name, profile = null, retentionDays = 90, maxEve
 		await writeStateFile(file, JSON.stringify(payload), { temporary: temporaryOf(dir, "usage.json") });
 		cache.remember(payload);
 	};
-	/** 排队执行一次读-改-写；只读闸置位时整个变更是 no-op。 */
+	/**
+	* 排队执行一次读-改-写；版本冲突时整个变更是 no-op。
+	*
+	* 闸在**临界区内部**由 diskVersionBlocksWrites 现读磁盘判定，不读内存里的
+	* readOnly——那个变量只用于日志去重与「闸已抬起」通知，删掉它不会让任何一次
+	* 写入被放行或拦住（2026-10-18 变异实证：删掉复位块后「删文件后写入必须恢复」
+	* 与「新计数落盘」两条断言仍然全绿）。
+	*
+	* 注释曾写「只读闸置位时整个变更是 no-op」——把判定归给内存闩锁。a61db2f（10-04，
+	* 首次提交）起就是这么写的，那时磁盘闸还没长出来，那句话是真的；403bfbc（10-05）
+	* 把守卫改成临界区内现读磁盘之后它就过期了，一直没被发现——因为没有任何断言
+	* 读它，它只是一句注释。
+	*/
 	const enqueue = (mutate) => writeQueue.enqueue(async () => {
 		if (await diskVersionBlocksWrites()) return;
 		const payload = await readThrough() ?? (loaded ? current : null) ?? {
@@ -1167,12 +1180,29 @@ function createFileUsageStore({ name, profile = null, retentionDays = 90, maxEve
 				dateKey
 			};
 		},
-		/** 今天的单模型计数（只含有记录的模型，dayCalls/dayTokens 口径，均跨日清零）。 */
+		/**
+		* 今天的单模型计数（只含有记录的模型，dayCalls/dayTokens 口径，均跨日清零）。
+		*
+		* 三种答案，与 {@link daily} / {@link trend} 同一条红线（wire.ts：读不到 ≠ 0）：
+		*   - 数组 —— 今天的单模型记录（只含有记录的模型；空数组 = 今天确实没有记录，
+		*     是**真实零**）；
+		*   - `null` —— **读不到**：载荷读不出来（损坏 / 形状不对 / 更新构建写的版本 /
+		*     存在却不可读）。面板渲染「—」，不是空排行。
+		*
+		* 这是 2026-10-18 补上的最后一块拼图：daily() 三态在 2026-10-16、trend() 在
+		* 本轮都补上了，perModelToday() 一直停在 `payload?.models ?? {}`——同一个坏文件
+		* 在头条画「—」、在单模型排行却画「还没有本地调用记录。」，同一份坏数据在
+		* 同一个卡片里给出两种答案。判据与 daily() 逐字一致：文件不存在才是真实的零，
+		* 文件在却读成空是信息丢失。
+		*
+		* @returns {Array<{modelId: string, calls: number, tokens: number|null, lastAt: string|null}> | null}
+		*/
 		async perModelToday() {
 			const payload = await cache.read();
+			if (payload === null) return await pathExists(file) ? null : [];
 			const todayKey = localDateKey(now());
 			const out = [];
-			for (const [modelId, counter] of Object.entries(payload?.models ?? {})) {
+			for (const [modelId, counter] of Object.entries(payload.models ?? {})) {
 				if (counter.day !== todayKey) continue;
 				out.push({
 					modelId,
@@ -1184,16 +1214,37 @@ function createFileUsageStore({ name, profile = null, retentionDays = 90, maxEve
 			out.sort((a, b) => b.calls - a.calls);
 			return out;
 		},
-		/** 最近 N 天趋势（含今天；缺桶 = 该日 0 次，真实零不是数据丢失）。 */
+		/**
+		* 最近 N 天趋势（含今天）。
+		*
+		* 三种答案，与 {@link daily} 同一条红线（wire.ts：读不到 ≠ 0）：
+		*   - `TrendBucket[]` —— 逐日桶，缺桶 = 该日 0 次（**真实零**：那天确实没有
+		*     记录，是已知答案）；
+		*   - `null` —— **读不到**：载荷读不出来（损坏 / 形状不对 / 更新构建写的
+		*     版本 / 存在却不可读）。面板渲染「—」，不是一片零柱。
+		*
+		* 判据与 daily() 逐字一致：**文件不存在**才是真实的零（这台 Host 从未经本
+		* 插件调用过），**文件在却读成空**是信息丢失。缺桶补 0 与整份读空补 0 是两件
+		* 完全不同的事，前者是数据，后者是伪造。
+		*
+		* 这是 2026-10-18 补上的一块拼图：daily() 早在 2026-10-16 就有了三态，
+		* trend() 一直只做了一半——`payload === null` 时照样逐日 push `{calls: 0}`，
+		* 于是「usage.json 被写坏」在今日计数上画「—」、在趋势图上却画 14 根结实的
+		* 零柱，同一份坏数据在两个区块给出两种答案。shapeWarnings 里那条 anomaly
+		* 确实会出现，但它说「usage.json 有问题」，不说「你看到的这条趋势线是假的」。
+		*
+		* @returns {TrendBucket[] | null}
+		*/
 		async trend(days = retentionDays) {
 			const payload = await cache.read();
+			if (payload === null) return await pathExists(file) ? null : [];
 			const out = [];
 			const cursor = now();
 			for (let offset = Number(days) - 1; offset >= 0; offset -= 1) {
 				const date = new Date(cursor);
 				date.setDate(date.getDate() - offset);
 				const key = localDateKey(date);
-				const bucket = payload?.days[key];
+				const bucket = payload.days[key];
 				out.push({
 					dateKey: key,
 					calls: bucket?.calls ?? 0,
@@ -1202,27 +1253,82 @@ function createFileUsageStore({ name, profile = null, retentionDays = 90, maxEve
 			}
 			return out;
 		},
-		/** 事件流（Newest-first，已截断）。 */
+		/**
+		* 事件流（Newest-first，已截断）。
+		*
+		* 三种答案，与 {@link daily} / {@link trend} 同一条红线（wire.ts：读不到 ≠ 0）：
+		*   - 数组 —— 读到的事件（空数组 = 确实没有事件，是**真实零**）；
+		*   - `null` —— **读不到**：载荷读不出来（损坏 / 形状不对 / 更新构建写的版本 /
+		*     存在却不可读）。面板渲染「—」，不是「暂无事件」。
+		*
+		* 与 perModelToday() 同一块拼图（2026-10-18）：`payload?.events ?? []` 把
+		* 「读不到」和「确实没有」合成同一种答案，坏文件在事件卡上假装岁月静好。
+		*
+		* @returns {QuotaEvent[] | null}
+		*/
 		async events() {
-			return [...(await cache.read())?.events ?? []];
+			const payload = await cache.read();
+			if (payload === null) return await pathExists(file) ? null : [];
+			return [...payload.events ?? []];
 		},
 		/** 最近一次解析异常（无异常为 null）——快照转 shapeWarnings。 */
 		anomaly() {
 			return anomaly;
-		},
-		/** 无秘密的状态（doctor 用）。 */
-		async state() {
-			const payload = await cache.read();
-			return {
-				file: profile === null ? join(stateDir(name), "usage.json") : file,
-				hasRecord: payload !== null,
-				days: Object.keys(payload?.days ?? {}).length,
-				events: payload?.events.length ?? 0,
-				readOnly
-			};
 		}
 	};
 }
+/**
+* 从 429/错误事件流推断「哪些模型当前额度耗尽」——**纯函数**，判定规则的唯一真源。
+*
+* 为什么需要它：官方只给**账户级**魔粒余额（`/openapi/v1/magicubes/balance`），
+* 没有 per-model 额度端点；而「哪个模型刚才在限频」恰恰是面板独家能答的问题。
+* 证据只有两类：事件流（`kind` 已按 llm-error-fix **重分类后**的口径，见
+* `usage-observer.ts` 头注）与单模型今日计数，本函数只用前者——计数分不清
+* 成功与失败（`recordCall` 按流计次、含失败），拿它当证据会猜。
+*
+* 判定规则（三条，全部可机械复现）：
+*   1. **只有 `kind:"quota"` 算证据**。`rate_limit` 是瞬时限频（peer 会退避
+*      重试，请求打得出去），`error` 是未知——把任何 429 都当耗尽是 0.2.0
+*      已修掉的误判（QUOTA 快速失败 vs RATE_LIMIT 退避，两条路不同）。
+*   2. **只在推断窗口内有效**：事件 `at` 落在 `[now - windowMinutes, +∞)`。
+*      窗口外的旧证据不算——免费额度按天重置，昨天的耗尽不该关掉今天的模型。
+*   3. **不推断恢复**：成功的流不发事件，所以「模型已恢复」在这份数据里
+*      **不可观测**。已恢复的模型最多灰显满一个窗口——方向是保守的（宁可少
+*      提供一会，不把注定 429 的模型放进选择器），且面板灰显带着原因，
+*      不是静默消失。
+*
+* 总量语义：`events` 是环形缓冲（`maxEvents` 截断、Newest-first），所以「窗口
+* 内没有证据」可能是**真没有**、也可能是**证据被截掉了**——后者只发生在
+* 极端刷屏（50 条以内）时。**方向是假阴性，不是保守**：证据被挤掉 → 集合收缩
+* → 一个仍耗尽的模型可能提前回灰、被重新放进选择器。以前这里写的是「保守收敛」，
+* 把危险方向说成了安全方向（下一轮会话会据此放松，所以改掉）。它之所以还能接受，
+* 是因为失败面很小且自限：窗口最长 1440min、事件天然会滑出，`reconcile` 每轮
+* 现算，下一个 quota 事件会立刻把它重新灰掉。时间戳解析不出的事件跳过，不猜。
+*
+* @param {readonly QuotaEvent[]|null|undefined} events - 事件流（任意顺序）。
+* @param {Date|number} [now] - 时钟源（测试注入）。
+* @param {number} [windowMinutes] - 推断窗口（分钟）。非正/非有限时返回空集
+*   ——总量防御：host-config 已把配置夹到 [5, 1440]，走到这里就是编程错误，
+*   「没有证据」比按坏窗口算出一个莫名的集合诚实。
+* @returns {string[]} 当前应视为额度耗尽的模型 id（去重、排序，稳定快照）。
+*/
+function exhaustedModelIds(events, now = Date.now(), windowMinutes = 60) {
+	if (!Number.isFinite(windowMinutes) || windowMinutes <= 0) return [];
+	const list = Array.isArray(events) ? events : [];
+	const nowMs = now instanceof Date ? now.getTime() : Number(now);
+	if (!Number.isFinite(nowMs)) return [];
+	const since = nowMs - windowMinutes * 6e4;
+	const out = /* @__PURE__ */ new Set();
+	for (const event of list) {
+		if (event === null || typeof event !== "object") continue;
+		if (event.kind !== "quota") continue;
+		const at = Date.parse(String(event.at));
+		if (!Number.isFinite(at) || at < since) continue;
+		const modelId = typeof event.modelId === "string" ? event.modelId : "";
+		if (modelId !== "") out.add(modelId);
+	}
+	return [...out].sort();
+}
 
 //#endregion
 //#region src/host/coalesced-fetch.ts
@@ -1853,6 +1959,16 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 * filter", which is the only safe default for a fresh install. A foreign file
 * reads the same way, which is precisely why `versionNote()` exists.
 *
+* Legacy adoption (ruling 2026-10-18): pre-§23 machines kept this state in
+* the SHARED directory; a profile-scoped store inherits it ONCE, when its own
+* file is missing. The seam lives in the read-through closure below, NOT in a
+* cache option, and the write-back rides this store's write chain; an explicit
+* `dir` (the tests) never inherits, and an explicit `forget()` is never
+* resurrected. The mirror rulings for the other three state stores live in
+* their own file headers: usage-prefs inherits the same way, usage / draw do
+* NOT adopt — the old shared files stay put, and `npm run doctor` reports them
+* as a `shared (legacy)` scope instead.
+*
 * @module dsh-connect-modelscope-token-plan/provider-store
 */
 /**
@@ -1994,8 +2110,8 @@ function resolveEnabledIds(stored, remembered) {
 */
 function createFileProviderStore(options = {}) {
 	const { dir, profile = null, ttlMs = STATE_READ_TTL_MS, logger } = options;
-	const stateDir$1 = dir ?? providerDir(profile);
-	const filePath = join(stateDir$1, "provider.json");
+	const stateDir$2 = dir ?? providerDir(profile);
+	const filePath = join(stateDir$2, "provider.json");
 	/**
 	* Write one payload atomically to this file.
 	*
@@ -2021,8 +2137,8 @@ function createFileProviderStore(options = {}) {
 			logger
 		});
 		if (refusal !== null) return refusal;
-		await ensureStateDir(stateDir$1);
-		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir$1, "provider.json") });
+		await ensureStateDir(stateDir$2);
+		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir$2, "provider.json") });
 		return null;
 	};
 	const legacyFile = dir === void 0 && profile ? join(stateDir(name), "provider.json") : null;
@@ -2295,8 +2411,14 @@ function createFileProviderStore(options = {}) {
 *     值被忽略」呈现成「从未保存过」。
 *
 * 与 provider-store 的一处**有意差异**：没有 legacy（pre-profile 共享目录）继承。
-* draw.json 随出图工具一起诞生，晚于按 profile 分段，市面上不存在共享布局里的
-* 旧 draw.json；provider.json 则需要（§23 之前它一直在共享目录）。
+* draw.json 随出图工具一起诞生，晚于按 profile 分段（git 史上成立），且宿主一直提供
+* profileContext 的机器上不存在共享布局里的旧 draw.json；provider.json 则需要
+* （§23 之前它一直在共享目录）。
+* 前提修正（2026-10-18）：「市面上不存在」只对宿主一直提供 profileContext 的机器成立。
+* 宿主不提供时 profile 恒为 null，draw.json 今至仍写共享目录；宿主升级后提供该服务
+* 时，同一个迁移窗口在 draw.json 上一模一样——那种窗口里旧 draw.json 不继承不搬，
+* doctor 以 shared (legacy) 作用域报出，出图开关与模型偏好回 patch 默认（与 usage.json 同侧：
+* 诊断可见 > 静默搬运）。
 *
 * doctor 覆盖：`describeDrawPayload` 给只读速览，`doctor.ts` 据此把 draw.json
 * 的「损坏 / 未知版本」报进症状表——写侧守卫挡覆盖，doctor 报静默降级。
@@ -2570,6 +2692,12 @@ function switchSource(panel) {
 * （无 profile 时落共享目录）。分段的意思是「这个 profile 想看多长」，两个 profile
 * 不互相覆盖。
 *
+* legacy 继承（2026-10-18 裁定）：pre-profile 共享目录里的 usage-prefs.json 在
+* 本 profile 自己的文件**不在场**时一次性继承——与 provider-store 同款手写缝
+*（读路径内触发、回填排进**本 store 的写队列**、显式清除不复活）。为什么这个
+* 搬而 usage.json 不搬：单值显示偏好回填无害，而历史计数是「本 profile 的账」，
+* 搬过来是把无 profile 时期的账算成这个 profile 的（usage-store.ts 头注的裁定）。
+*
 * 优先级与所有 opt-in 开关同一份裁决（`switch-precedence.ts`）：面板保存值赢，
 * 否则 `cordis.patch.yml` 的 `trendDays` 说了算；两者都会在 host-config 里被夹进
 * 保留窗口之内（`retentionDays`）——**画得比留得多**会把已剪的日子画成 0。
@@ -2648,8 +2776,8 @@ function resolveWindowDays(panel, fallback, maxDays) {
 */
 function createFileUsagePrefsStore(options = {}) {
 	const { dir, profile = null, ttlMs = STATE_READ_TTL_MS, logger } = options;
-	const stateDir = usagePrefsDir(profile, dir);
-	const filePath = join(stateDir, "usage-prefs.json");
+	const stateDir$1 = usagePrefsDir(profile, dir);
+	const filePath = join(stateDir$1, "usage-prefs.json");
 	/**
 	* 写一份 payload 并落盘。
 	*
@@ -2665,18 +2793,19 @@ function createFileUsagePrefsStore(options = {}) {
 			logger
 		});
 		if (refusal !== null) return refusal;
-		await ensureStateDir(stateDir);
-		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir, "usage-prefs.json") });
+		await ensureStateDir(stateDir$1);
+		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir$1, "usage-prefs.json") });
 		return null;
 	};
 	/** 写串行化：读-改-写必须排队（详见{@link createStateWriteQueue}）。 */
 	const writeQueue = createStateWriteQueue();
 	/**
-	* 解析一份 payload；认不出的版本读作「没设过」但**记住**版本号——读侧宽容、
-	* versionNote 负责把宽容说出口（写侧守卫已挡住覆盖，两半合起来才是 ADR-006）。
+	* 解析一份路径上的 payload；认不出的版本读作「没设过」但**记住**版本号——读侧
+	* 宽容、versionNote 负责把宽容说出口（写侧守卫已挡住覆盖，两半合起来才是
+	* ADR-006）。
 	*/
-	const parsePayload = async () => {
-		const source = obj(await readStateJson(filePath));
+	const parseAt = async (path) => {
+		const source = obj(await readStateJson(path));
 		const version = typeof source.version === "number" ? source.version : null;
 		if (!isKnownUsagePrefsVersion(version)) return {
 			windowDays: null,
@@ -2687,7 +2816,21 @@ function createFileUsagePrefsStore(options = {}) {
 			version
 		};
 	};
-	const cache = createStateReadCache(parsePayload, { ttlMs });
+	/** 读本 profile 自己的文件。 */
+	const parsePayload = async () => parseAt(filePath);
+	const legacyFile = dir === void 0 && profile ? join(stateDir(name), "usage-prefs.json") : null;
+	const cache = createStateReadCache(async () => {
+		const own = await parsePayload();
+		if (own.windowDays !== null || legacyFile === null || own.version !== null) return own;
+		const legacy = await parseAt(legacyFile);
+		if (legacy.windowDays === null) return own;
+		await writeQueue.enqueue(() => writePayload({
+			version: 1,
+			windowDays: legacy.windowDays,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}).then(() => void 0, () => void 0));
+		return legacy;
+	}, { ttlMs });
 	/**
 	* 读当前 payload。
 	* @returns {Promise<UsagePrefsPayload>}
@@ -3652,6 +3795,14 @@ function sleep(ms, signal) {
 /** 当前缺席原因（`null` = 未登记 / 已清掉）。 */
 let note = null;
 /**
+* 本次挂载是否真的把工具注册上了。
+*
+* 与 `note` 的区别见文件头：`note` 是「注册尝试过且失败的原因」，这一位是「注册
+* 成功与否」。开关在挂载后才翻开的场景，两者都是「没有缺席原因 + 没注册上」，
+* 只有这一位能把它认出来。
+*/
+let mounted = false;
+/**
 * 记下缺席原因（`null` 清空）。
 * @param {DrawToolAbsentReason|null} reason - 原因码。
 * @returns {void}
@@ -3667,11 +3818,28 @@ function drawToolNote() {
 	return note;
 }
 /**
+* 记下「本次挂载已注册上」。只有注册路径走完才置 true；缺席与「开关没开」都是
+* false。
+* @param {boolean} value - 是否注册成功。
+* @returns {void}
+*/
+function setDrawToolMounted(value) {
+	mounted = value === true;
+}
+/**
+* 读「本次挂载是否注册上了」。
+* @returns {boolean} true = 注册成功。
+*/
+function drawToolMounted() {
+	return mounted;
+}
+/**
 * 清空（卸载时调用：下一个 Host 生命周期从干净的「未登记」开始）。
 * @returns {void}
 */
 function resetDrawToolNote() {
 	note = null;
+	mounted = false;
 }
 
 //#endregion
@@ -3738,6 +3906,7 @@ async function registerDrawTool(ctx, wiring, deps = {}) {
 	const { settings, configError, tokenStore, inference, drawStore, publisher, logger } = wiring;
 	const loggerFor = logger ?? ctx.logger;
 	setDrawToolNote(null);
+	setDrawToolMounted(false);
 	try {
 		if (configError !== null) return;
 		const panelValue = drawStore ? await drawStore.enabled().catch(() => null) : null;
@@ -3781,6 +3950,7 @@ async function registerDrawTool(ctx, wiring, deps = {}) {
 			},
 			isDisposed
 		}));
+		setDrawToolMounted(true);
 	} catch (error) {
 		setDrawToolNote("registry-refused");
 		loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets(errMsg(error))}) — the tool is absent`);
@@ -4365,6 +4535,7 @@ function createProviderPublisher(deps = {}) {
 				entries: state.entries,
 				enabledIds: state.enabledIds,
 				baseUrl: effectiveSettings.apiBase,
+				maxTokensOverrides: effectiveSettings.maxTokensOverrides ?? {},
 				resolveApiKey: effectiveResolveApiKey,
 				get: effectiveGetLlm,
 				unavailableModelIds: state.unavailableIds,
@@ -4564,7 +4735,8 @@ function syncSignaturesAfterPublish(state) {
 *   - **desired state**（操作者想要什么）= `providerStore` 里的开关 + 允许
 *     清单 + 窗口覆盖。它只有一个家，轮询和路由都只读它、不各写一份；
 *   - **reconcile 一遍** = 读 desired → 带窗口覆盖拉目录 → 复查 desired
-*     （fetch 期间被改就重跑，不等下一轮）→ 把「当前目录 + 当前清单」交给
+*     （fetch 期间被改就重跑，不等下一轮）→ 算这一轮的额度耗尽集合（事件流 +
+*     纯函数 `exhaustedModelIds`）→ 把「当前目录 + 当前清单 + 耗尽集合」交给
 *     publisher（它自己重读开关，single source 不变）；
 *   - **触发方全部降级为「标记 dirty」**：挂载、轮询定时器、四条写路由。
 *     谁都不用记得「别人是不是也在 publish」——队列性质由本模块的串行链保证。
@@ -4590,20 +4762,40 @@ function syncSignaturesAfterPublish(state) {
 * 最多收敛成两遍 reconcile，不会排 N 遍。调用方 await 返回的 promise，即
 * 「我的触发已被消费」。
 * @param {ProviderReconcilerDeps} deps - wiring 子集。
-* @returns {{reconcile: () => Promise<void>}} 触发一次收敛。
+* @returns {{reconcile: () => Promise<void>; health: () => {{ lastError: unknown }} }}
 */
 function createProviderReconciler(deps) {
-	const { providerStore, inference, publisher, logger } = deps;
+	const { settings, providerStore, inference, publisher, usageEvents, logger } = deps;
 	/**
-	* 读一次 desired。三路都 `.catch(() => null)`：读不到按「未设置」降级，
-	* 与开关/清单/覆盖各自的读侧纪律一致——一次读失败不该把收敛打掉。
+	* 把一次 store 读取收成「值或 null」——**同步抛与异步拒收都降级**。
+	*
+	* store 是外部契约：当前三个 store 方法都是 `async`（同步抛不可达），但这
+	* 不是可依赖的保证——病态实现、未来改签名、测试替身都可能同步抛。同步抛
+	* 曾在 `Promise.all([a(), b(), c()])` 的**数组构造处**逃逸，把整个 executor
+	* 变成 rejection（2026-10-18 实测的链毒化入口，见 {@link reconcile} 的防
+	* 毒化注释）。一次读失败按「未设置」降级是本文件既有纪律，同步抛与拒收
+	* 不该得到不同待遇。
+	* @template T
+	* @param {() => T | Promise<T>} read - 一次 store 读取。
+	* @returns {Promise<T | null>} 读到的值，或 null（读不到）。
+	*/
+	const settle = (read) => {
+		try {
+			return Promise.resolve(read()).catch(() => null);
+		} catch {
+			return Promise.resolve(null);
+		}
+	};
+	/**
+	* 读一次 desired。三路都降级为「未设置」：读不到按未设置处理，与开关/清单/
+	* 覆盖各自的读侧纪律一致——一次读失败不该把收敛打掉。
 	* @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)
+			settle(() => providerStore.enabled()),
+			settle(() => providerStore.enabledIds()),
+			settle(() => providerStore.contextWindow())
 		]);
 		return {
 			enabled,
@@ -4618,6 +4810,26 @@ function createProviderReconciler(deps) {
 		desired.contextWindow
 	]);
 	/**
+	* 读这一轮要发布的「额度耗尽集合」。
+	*
+	* 事件读失败**不抛**（收敛不能因为一条观测路径坏了就停）：降级为空集并留一条
+	* warn——与目录 fetch 失败同纪律（原因不丢、下一轮重试）。方向要说清：空集
+	* 意味着「没有证据」，picker 会提供那些模型；这是把可观测失败换算成「暂时
+	* 没有证据」的取舍，比让整个收敛链崩掉诚实。
+	* @returns {Promise<string[]>}
+	*/
+	const readUnavailable = async () => {
+		if (usageEvents === void 0) return [];
+		let events;
+		try {
+			events = await usageEvents();
+		} catch (error) {
+			logger?.warn?.(`${name}: usage events read failed (${redactSecrets(errMsg(error))}) — no quota-exhaustion evidence this pass`);
+			return [];
+		}
+		return exhaustedModelIds(events, /* @__PURE__ */ new Date(), settings.exhaustionWindowMinutes);
+	};
+	/**
 	* 收敛一遍：读 desired → 拉目录 → 复查 desired → publish。
 	* @returns {Promise<void>}
 	*/
@@ -4637,8 +4849,9 @@ function createProviderReconciler(deps) {
 		}
 		const entries = Array.isArray(catalog?.entries) ? catalog.entries : [];
 		const enabledIds = resolveEnabledIds(after.enabledIds, publisher.state.enabledIds);
+		const unavailable = await readUnavailable();
 		try {
-			await publisher.publish(entries, enabledIds, []);
+			await publisher.publish(entries, enabledIds, unavailable);
 		} catch (error) {
 			logger?.warn?.(`${name}: publish failed (${redactSecrets(errMsg(error))}) — the catalog is current, only the provider registration did not land`);
 		}
@@ -4648,13 +4861,21 @@ function createProviderReconciler(deps) {
 	/** 有新触发待消费。闭包状态，不暴露——触发方只看得见 {@link reconcile}。 */
 	let dirty = false;
 	/**
+	* 最近一次「未被 runOnce 自行记档」的意外反抗（executor 层面漏网的抛，如
+	* `publisher.state` 的 getter 同步抛），下一遍成功即清空。路由侧 await 拿到
+	* `result` 会自行 respondError；但**轮询侧 `void reconcile()` 会把它丢掉**——
+	* 这份 lastError + 一条 warn 是「这一遍没收敛成」对操作员/测试唯一可观测的
+	* 记档（否则链的防毒化会把它连同结果一起吞成 0 痕迹，见 {@link reconcile} 注释）。
+	*/
+	let lastError = null;
+	/**
 	* 触发一次收敛。幂等且可重入：在途时只置 dirty，由在途那一轮替本调用消费
 	* （N 次连续触发最多收敛成两遍 reconcile，不会排 N 遍）。
 	* @returns {Promise<void>} 本触发已被消费（注册态已反映 desired）后 resolve。
 	*/
 	const reconcile = () => {
 		dirty = true;
-		return chain = chain.then(async () => {
+		const result = chain.then(async () => {
 			let guard = 0;
 			while (dirty) {
 				dirty = false;
@@ -4662,8 +4883,20 @@ function createProviderReconciler(deps) {
 				if (++guard > 20) break;
 			}
 		});
+		result.then(() => {
+			lastError = null;
+		}, (error) => {
+			lastError = error;
+			logger?.warn?.(`${name}: reconcile pass failed (${redactSecrets(errMsg(error))}); state will be reconciled on the next trigger`);
+		});
+		chain = result.then(() => void 0, () => void 0);
+		return result;
+	};
+	return {
+		reconcile,
+		/** 最近一次未被记档的意外反抗（成功即清空）；null = 当前健康。 */
+		health: () => ({ lastError })
 	};
-	return { reconcile };
 }
 
 //#endregion
@@ -4769,7 +5002,7 @@ async function buildSnapshotBody(wiring) {
 		const panel = await providerStore.enabled().catch(() => null);
 		const enabled = resolveSwitchEnabled(panel, settings.registerProvider);
 		const source = switchSource(panel);
-		const roster = rosterWithAvailability(modelEntries, []);
+		const roster = rosterWithAvailability(modelEntries, publisher.state.unavailableIds ?? [], settings.maxTokensOverrides);
 		const stored = await providerStore.enabledIds().catch(() => null);
 		const enabledIds = resolveEnabledIds(stored, publisher.state.enabledIds);
 		const allowedList = parseAllowedList(enabledIds);
@@ -4806,7 +5039,8 @@ async function buildSnapshotBody(wiring) {
 			effectiveModel: choice.id,
 			effectiveSource: choice.source,
 			absentReason: drawToolNote(),
-			mountPending: resolveSwitchEnabled(panel, settings.drawEnabled) === true && drawToolNote() !== null,
+			mountPending: resolveSwitchEnabled(panel, settings.drawEnabled) === true && drawToolMounted() !== true,
+			preferredInCatalog: preferred === null ? null : models.ok ? candidates.some((row) => row.id === preferred) : null,
 			toolName: "modelscope_draw_image"
 		};
 	})());
@@ -4846,15 +5080,15 @@ async function buildSnapshotBody(wiring) {
 		},
 		quota: {
 			daily: { usedLocal },
-			perModel: perModel.ok ? perModel.value : [],
+			perModel: perModel.ok ? perModel.value : null,
 			countingNote: "local-counting"
 		},
-		events: events.ok ? events.value : [],
+		events: events.ok ? events.value : null,
 		trend: {
 			days: windowDays,
 			windowDays: panelWindow,
 			maxDays: settings.retentionDays,
-			buckets: trend.ok ? trend.value : []
+			buckets: trend.ok ? trend.value : null
 		},
 		models: {
 			available: models.ok,
@@ -5334,7 +5568,7 @@ function registerProviderRoute(ctx, wiring) {
 			if (options.tolerateCatalogFailure !== true) throw error;
 			catalogError = redactedError(error);
 		}
-		const roster = rosterWithAvailability(entries, []);
+		const roster = rosterWithAvailability(entries, publisher.state.unavailableIds ?? [], settings.maxTokensOverrides);
 		const allowedList = parseAllowedList(enabledIds);
 		const modelCount = roster.length;
 		return {
@@ -5502,16 +5736,31 @@ function registerProviderRoute(ctx, wiring) {
 * @module dsh-connect-modelscope-token-plan/routes/draw
 */
 /**
-* 读目录条目，读不到按空目录降级。
+* 读目录条目。
 *
 * 与 provider 路由同一条纪律：GET 不能因为一次目录失败就把整个面板状态打掉——
 * 出图候选为空只影响「能不能挑模型」，不影响开关的显示。
+*
+* 但「空目录」和「目录读不到」必须分开（红线 3）：后者要能回答「首选模型还在
+* 不在」时说「不知道」而不是「不在」。所以这里返回 `{ ok, entries }`，调用方
+* 按 ok 决定是断言还是弃权。
+*
 * @param {object} inference - inference client。
-* @returns {Promise<unknown[]>} 归一目录条目。
+* @returns {Promise<{ok: boolean, entries: unknown[]}>} 目录读取结果与归一条目。
 */
 async function readEntries(inference) {
-	const catalog = await inference.fetchModels().catch(() => ({ entries: [] }));
-	return Array.isArray(catalog?.entries) ? catalog.entries : [];
+	try {
+		const catalog = await inference.fetchModels();
+		return {
+			ok: true,
+			entries: Array.isArray(catalog?.entries) ? catalog.entries : []
+		};
+	} catch {
+		return {
+			ok: false,
+			entries: []
+		};
+	}
 }
 /**
 * 注册出图路由（两条路径）。
@@ -5529,10 +5778,10 @@ function registerDrawRoute(ctx, wiring) {
 	const snapshot = async (extra = {}) => {
 		const panelSwitch = await optional(drawStore.enabled());
 		const panelModelId = await optional(drawStore.modelId());
-		const entries = await readEntries(inference);
-		const candidates = drawCandidates(entries);
+		const catalog = await readEntries(inference);
+		const candidates = drawCandidates(catalog.entries);
 		const preferredModelId = resolveSwitchValue(panelModelId, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
-		const choice = resolveDrawModelChoice(entries, void 0, preferredModelId ?? void 0);
+		const choice = resolveDrawModelChoice(catalog.entries, void 0, preferredModelId ?? void 0);
 		return {
 			ok: true,
 			enabled: resolveSwitchEnabled(panelSwitch, settings.drawEnabled),
@@ -5550,9 +5799,14 @@ function registerDrawRoute(ctx, wiring) {
 			*
 			* 工具无法注销（peer 的 tools registry 没有 unregister），所以开关翻转只在
 			* 下次 Host 启动时生效。面板据此显示一句说明——否则用户会以为开关坏了。
-			* 判据：开关为开且本次挂载尚未注册成功（或缺席原因未知）。
+			* 判据：开关为开且**本次挂载没注册上**。
+			*
+			* 注意判据不是「有缺席原因」：缺席原因非 null 表示注册尝试过且失败，而挂载
+			* 那一刻开关是关的（用户之后才翻开）时 absentReason 为 null、却同样没注册
+			* 上——后者才是最需要这句提示的场景。见 `draw-tool-state.ts` 文件头。
 			*/
-			mountPending: resolveSwitchEnabled(panelSwitch, settings.drawEnabled) === true && drawToolNote() !== null,
+			mountPending: resolveSwitchEnabled(panelSwitch, settings.drawEnabled) === true && drawToolMounted() !== true,
+			preferredInCatalog: preferredModelId === null ? null : catalog.ok ? candidates.some((row) => row.id === preferredModelId) : null,
 			toolName: "modelscope_draw_image",
 			...extra
 		};
@@ -5833,6 +6087,7 @@ function apply(ctx, config = {}, deps = {}) {
 		providerStore,
 		inference,
 		publisher,
+		usageEvents: () => usageStore.events(),
 		logger: ctx.logger
 	});
 	const wiring = {
@@ -5850,10 +6105,14 @@ function apply(ctx, config = {}, deps = {}) {
 	};
 	const offs = registerRoutes(ctx, wiring);
 	ctx.effect(() => {
-		reconcile();
+		reconcile().catch((error) => {
+			ctx.logger?.warn?.(`${name}: mount reconcile failed (${redactSecrets(errMsg(error))})`);
+		});
 		registerDrawTool(ctx, wiring, deps);
 		const timer = setInterval(() => {
-			reconcile();
+			reconcile().catch((error) => {
+				ctx.logger?.warn?.(`${name}: scheduled reconcile failed (${redactSecrets(errMsg(error))})`);
+			});
 		}, settings.pollSeconds * 1e3);
 		return () => {
 			clearInterval(timer);