dsh-xdpool 2.6.1 → 2.6.2

package/lib/index.js

@@ -3,7 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import crypto, { createDecipheriv, createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, truncateSync, writeFileSync } from "node:fs";
-import { chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { execFile, execFileSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -3589,12 +3589,46 @@ async function cheapIdentityIdFromFile(path) {
 	}
 }
 /**
+* The `uin` of a credential file, read WITHOUT the expiry gate.
+*
+* `parseWorkBuddyAuth` deliberately refuses an expired document, which is exactly the
+* state this is asked about — so the identity has to come from the raw JSON. `uin` and not
+* `uid`: `uin` is the billing identity, so two sign-ins of one person match even when the
+* desktop app wrote them from different installs.
+*/
+async function cheapUinFromFile(path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(path, "utf8"));
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	const document = parsed;
+	const uin = (typeof document["account"] === "object" && document["account"] !== null ? document["account"] : document)["uin"];
+	return typeof uin === "string" && uin !== "" ? uin : void 0;
+}
+/**
 * Why a file could not become an account.
 *
-* Distinguishing "encrypted" matters most: it is actionable (start the desktop
-* app, or set the executable override), whereas "malformed" means the file is
-* simply not a credential. Reporting them alike would send the user looking for
-* a fix that cannot work.
+* The distinctions matter because the REMEDIES differ, and a wrong label sends the reader
+* after a fix that cannot work:
+*
+*   - `encrypted`   — the desktop app holds the key; start it, or set the executable
+*                     override. Actionable.
+*   - `expired`     — the file IS a credential, correctly formed, whose refresh window has
+*                     closed. Nothing to fix: sign in again, or delete the snapshot. This
+*                     used to be reported as `malformed`, which reads as "this file is not
+*                     a credential" and sends the user looking for a format problem that
+*                     does not exist — the reported confusion over three 2026-10-08
+*                     snapshots whose tokens had simply aged out.
+*   - `unreadable`  — the bytes could not be read at all.
+*   - `malformed`   — genuine: unparseable, or parseable but not a credential shape.
+*
+* `expired` is decided by re-parsing the document the same way `parseWorkBuddyAuth` does,
+* which is the only way to tell "a credential that aged out" from "not a credential". A
+* document that parses as JSON but carries no token stays `malformed`: those are three
+* different facts and collapsing any two of them costs the reader the diagnosis.
 */
 async function skipReasonFor(path) {
 	let text;
@@ -3604,12 +3638,28 @@ async function skipReasonFor(path) {
 		return "unreadable";
 	}
 	if (text.includes("\"$wbEncrypted\"")) return "encrypted";
+	let parsed;
 	try {
-		JSON.parse(text);
-		return "malformed";
+		parsed = JSON.parse(text);
 	} catch {
 		return "malformed";
 	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return "malformed";
+	const document = parsed;
+	const auth = typeof document["auth"] === "object" && document["auth"] !== null ? document["auth"] : document;
+	const token = auth["accessToken"];
+	if (typeof token !== "string" || token === "") return "malformed";
+	/**
+	* It HAS a token, so the only remaining reason to skip it is a closed refresh window.
+	* Mirrors the guard in `parseWorkBuddyAuth`, and falls back to `malformed` when the
+	* window cannot be read — an unknown expiry is not evidence of expiry.
+	*/
+	const refreshRaw = auth["refreshExpiresAt"];
+	if (typeof refreshRaw === "number") {
+		const refreshAt = expiryToMs$1(refreshRaw);
+		if (refreshAt > 0 && refreshAt < Date.now()) return "expired";
+	}
+	return "malformed";
 }
 /**
 * Build the field opener, or undefined when the app cannot supply its key.
@@ -3911,6 +3961,46 @@ var WorkBuddyAccountPool = class {
 	skippedFilesInOrder() {
 		return this.skippedFiles;
 	}
+	/**
+	* Delete expired snapshots that a newer credential for the same account supersedes.
+	*
+	* Returns the paths actually removed. See the call site for the full safety rule; the
+	* short version is that it touches ONLY files classified `expired`, ONLY when the same
+	* `uin` is already served by a different (loaded) file, and never a live file.
+	*
+	* `uin` rather than `uid`: it is the billing identity, so two sign-ins of one person
+	* match even when the desktop app wrote them from different installs. A file whose
+	* identity cannot be read is left alone — deleting a credential on a guess is worse than
+	* keeping a dead one on the card.
+	*/
+	async pruneExpiredSnapshots(skipped, loaded) {
+		const expired = skipped.filter((entry) => entry.reason === "expired");
+		if (expired.length === 0) return [];
+		const liveNames = /* @__PURE__ */ new Set([WORKBUDDY_LIVE_FILENAME, "workbuddy-desktop-ai.info"]);
+		/**
+		* The identities already served by a file that loaded in this same scan.
+		*
+		* Taken from the parsed credentials rather than by re-reading each file: `found`
+		* already carries `uin`, and a second read of a file that just parsed would only add a
+		* chance to fail.
+		*/
+		const servedUins = /* @__PURE__ */ new Set();
+		for (const credential of loaded) if (credential.uin !== void 0 && credential.uin !== "") servedUins.add(credential.uin);
+		if (servedUins.size === 0) return [];
+		const removed = [];
+		for (const entry of expired) {
+			if (liveNames.has(basename(entry.path))) continue;
+			const uin = await cheapUinFromFile(entry.path);
+			if (uin === void 0 || !servedUins.has(uin)) continue;
+			try {
+				await unlink(entry.path);
+				removed.push(entry.path);
+			} catch (error) {
+				this.logger?.warn?.(`dsh-xdpool: could not remove expired snapshot ${entry.path}: ${String(error)}`);
+			}
+		}
+		return removed;
+	}
 	/** Rescan the auth directories and merge newly discovered accounts. */
 	async scan() {
 		const found = [];
@@ -3937,6 +4027,33 @@ var WorkBuddyAccountPool = class {
 		}
 		this.skippedFiles = skipped;
 		if (skipped.length > 0) this.logger?.warn?.(`dsh-xdpool: ${skipped.length} credential file(s) could not be read; ${found.length} account(s) still loaded. Reasons: ` + [...new Set(skipped.map((s) => s.reason))].join("; "));
+		/**
+		* Remove expired snapshots whose account is served by a newer credential.
+		*
+		* A rotated sign-in leaves the old snapshot on disk forever: the desktop app writes a
+		* new `workbuddy-desktop.<ts>.<pid>.<uuid>.info` each time and never deletes the
+		* previous one. Within a month every one of them passes its `refreshExpiresAt` and the
+		* card starts listing a growing pile of "expired" files the user cannot act on —
+		* they are dead weight from a sign-in that already succeeded.
+		*
+		* The safety rule is narrow on purpose, because deleting a credential file is
+		* destructive and the auth directory belongs to another application:
+		*
+		*   - ONLY files this scan classified as `expired` — never `encrypted`, `unreadable`
+		*     or `malformed`, which may be the very file holding a working key;
+		*   - ONLY when the SAME account (by `uin`, the billing identity) was loaded from a
+		*     DIFFERENT file, i.e. a newer credential exists to serve it;
+		*   - never the live `workbuddy-desktop.info` / `workbuddy-desktop-ai.info`, which the
+		*     running app owns and rewrites.
+		*
+		* Anything skipped for not meeting all three is left alone and keeps its entry on the
+		* card, so the user still learns it is there.
+		*/
+		const cleaned = await this.pruneExpiredSnapshots(skipped, found);
+		if (cleaned.length > 0) {
+			this.skippedFiles = skipped.filter((entry) => !cleaned.includes(entry.path));
+			this.logger?.info?.(`dsh-xdpool: removed ${cleaned.length} expired credential snapshot(s) superseded by a newer sign-in`);
+		}
 		if (this.externalSource !== void 0) try {
 			const external = await this.externalSource();
 			for (const credential of external) {
@@ -4040,6 +4157,86 @@ var WorkBuddyAccountPool = class {
 		});
 	}
 	/**
+	* The pool ordered into three bands, so a resting account is deferred instead of
+	* discarded.
+	*
+	* `available()` answers a binary question, and a binary answer loses the
+	* distinction that matters most when a pool is under pressure:
+	*
+	*   - an account that still HAS credits but was rate-limited a moment ago is
+	*     healthy — it should be tried AFTER the others, not treated as gone;
+	*   - an account resting after a failure is the last resort, but it is still a
+	*     resort: when it is the only one, trying it beats failing the request.
+	*
+	* A pool that drops both from the list turns "every account is cooling for
+	* twenty more seconds" into an error the user reads as "no account available",
+	* which is a different and much more alarming statement.
+	*
+	* The bands:
+	*
+	*   1. `ready`    — passes every gate `available()` checks.
+	*   2. `limited`  — region-eligible and not disabled/reserved, but cooling for
+	*                   this model or account-wide. Ordered by when it comes back,
+	*                   so the account that recovers first is spent first.
+	*   3. `resting`  — sign-in was rejected by the upstream. It never heals on a
+	*                   timer, so it is only tried when 1 and 2 are both empty.
+	*
+	* `disabled` and `reserve` accounts appear in NO band: those are user choices,
+	* and overriding them is not resilience, it is ignoring an instruction.
+	*
+	* Kept separate from `available()` rather than replacing it, so the binary
+	* question still has a binary answer for callers that want one (diagnostics,
+	* the status document) without either copy drifting from the other.
+	*/
+	rankedPool(now, modelId, region, reserveExempt) {
+		const ready = [];
+		const limited = [];
+		const resting = [];
+		for (const account of this.accounts) {
+			if (this.disabledIds.has(account.id)) continue;
+			const reserve = this.creditReserves.get(account.id);
+			if (!reserveExempt?.has(account.id) && reserve !== void 0 && reserve > 0) {
+				const balance = this.creditBalances.get(account.id);
+				if (balance !== void 0 && balance <= reserve) continue;
+			}
+			if (region !== void 0 && regionOf(account.credential.domain) !== region) continue;
+			const deadUntil = account.credentialDeadUntilMs ?? 0;
+			const coolUntil = account.cooldownUntilMs;
+			const modelUntil = modelId === void 0 ? 0 : account.modelCooldowns[modelId] ?? 0;
+			if (deadUntil > now) {
+				resting.push(account);
+				continue;
+			}
+			/**
+			* Only a MODEL-level cooldown earns a retry; an account-wide one does not.
+			*
+			* The distinction is what keeps the tier honest. A 429 on one model leaves
+			* the account working for every other model, so trying it again for a
+			* different model is reasonable and often succeeds. An account-wide cooldown
+			* (credits exhausted, quota wall) means the gateway has already said no to
+			* this account as a whole — retrying it spends a round trip to be told the
+			* same thing, and the caller then reports 502 where the truthful answer was
+			* 429. That degradation is worse than the resilience is worth, so the
+			* account-wide case stays out of play entirely.
+			*/
+			if (coolUntil > now) continue;
+			if (modelUntil > now) {
+				limited.push({
+					account,
+					backAt: modelUntil
+				});
+				continue;
+			}
+			ready.push(account);
+		}
+		limited.sort((a, b) => a.backAt - b.backAt);
+		return {
+			ready,
+			limited: limited.map((entry) => entry.account),
+			resting
+		};
+	}
+	/**
 	* Why no account is available right now, for an accurate error.
 	*
 	* The pool can be empty for reasons that need OPPOSITE remedies: nobody is
@@ -4324,27 +4521,82 @@ var WorkBuddyAccountPool = class {
 		if (this.accounts.length === 0) await this.scan();
 		const maxTries = this.accounts.length + 1;
 		for (let attempt = 0; attempt < maxTries; attempt += 1) {
-			let pool = this.available(Date.now(), modelId, region, reserveExempt);
-			if (pool.length === 0 && attempt === 0) {
+			let bands = this.rankedPool(Date.now(), modelId, region, reserveExempt);
+			if (bands.ready.length === 0 && bands.limited.length === 0 && bands.resting.length === 0 && attempt === 0) {
 				await this.scan();
-				pool = this.available(Date.now(), modelId, region, reserveExempt);
+				bands = this.rankedPool(Date.now(), modelId, region, reserveExempt);
 			}
-			if (pool.length === 0) return void 0;
+			/**
+			* Fall through the bands, in order — but the fall-through is a STAGE, not a
+			* concatenation, and only `ready` is offered to the strategy when it is
+			* non-empty.
+			*
+			* This distinction is the whole correctness of the change. A strategy like
+			* `balanced` draws from the pool by weight and does not read the order at
+			* all, so handing it `[...ready, ...limited]` would let it pick a cooling
+			* account while a healthy one was sitting right there — silently breaking
+			* the promise "a cooling account is never chosen while a healthy one
+			* exists".
+			*
+			* The wider rule: a band is only tried when every earlier band is EMPTY.
+			* That keeps the truthful error intact — "every account is cooling for this
+			* model" must stay a 429 answered without touching the transport, not a
+			* round trip that comes back 502. Resilience is a last resort, not a
+			* preference, and a pool where nothing is ready has already told the caller
+			* exactly what is wrong.
+			*/
+			const stages = bands.ready.length > 0 ? [bands.ready] : [];
+			if (stages.length === 0) return;
 			if (this.preferredAccountId !== void 0) {
-				const preferred = pool.find((account) => account.id === this.preferredAccountId);
+				const preferred = bands.ready.find((account) => account.id === this.preferredAccountId);
 				if (preferred !== void 0 && await this.ensureFresh(preferred)) return preferred;
 			}
 			if (this.distribution === "sticky") {
-				const bound = this.affinityAccount(pool, conversationKey);
+				const bound = this.affinityAccount(bands.ready, conversationKey);
 				if (bound !== void 0 && await this.ensureFresh(bound)) return bound;
 			}
-			const account = this.distribution === "round-robin" || this.distribution === "sticky" ? this.pickRoundRobin(pool) : this.distribution === "balanced" ? this.pickByWeight(pool) : this.distribution === "expiry" ? this.pickByExpiry(pool) : pool[0];
-			if (account === void 0) return void 0;
-			if (!await this.ensureFresh(account)) continue;
-			if (this.distribution === "sticky" && conversationKey !== void 0 && conversationKey !== "") this.bindAffinity(conversationKey, account.id);
-			return account;
+			/**
+			* An account whose balance has never been read goes first, ONCE — but only
+			* under `priority`.
+			*
+			* The reasoning is `priority`-specific: that mode drains one account at a
+			* time, so a fresh account appended to the pool would sit untouched behind an
+			* account that is nearly spent, and the pool would never learn what the new
+			* one has. Trying it once makes its own answer fill in the blank.
+			*
+			* `round-robin`, `balanced`, `sticky` and `expiry` already reach a new
+			* account by their own rule — the cursor walks to it, the weight draw will
+			* eventually pick it, a new conversation moves on to it — so jumping the
+			* queue here would not add information, it would only override the
+			* distribution the user chose. That was a real regression: it pinned every
+			* rotation to the first unprobed account.
+			*
+			* Restricted to `ready` as well: an account that is cooling is not made more
+			* attractive by being unknown, and probing it would spend a request to learn
+			* a number that does not change whether it can answer.
+			*/
+			const probe = this.distribution === "priority" && bands.ready.length > 1 ? bands.ready.find((account) => !this.creditBalances.has(account.id)) : void 0;
+			if (probe !== void 0 && this.isStageEligible(probe, bands)) {
+				if (await this.ensureFresh(probe)) return probe;
+			}
+			for (const pool of stages) {
+				const account = this.distribution === "round-robin" || this.distribution === "sticky" ? this.pickRoundRobin(pool) : this.distribution === "balanced" ? this.pickByWeight(pool) : this.distribution === "expiry" ? this.pickByExpiry(pool) : pool[0];
+				if (account === void 0) continue;
+				if (!await this.ensureFresh(account)) continue;
+				if (this.distribution === "sticky" && conversationKey !== void 0 && conversationKey !== "") this.bindAffinity(conversationKey, account.id);
+				return account;
+			}
 		}
 	}
+	/**
+	* Whether an account belongs to a band that is currently in play.
+	*
+	* Only `ready` accounts are eligible for the probe shortcut: picking a resting
+	* account ahead of a healthy one is the very thing the bands exist to prevent.
+	*/
+	isStageEligible(account, bands) {
+		return bands.ready.includes(account);
+	}
 	/** How the pool currently spreads requests. Shown on the card. */
 	currentDistribution() {
 		return this.distribution;
@@ -5103,6 +5355,17 @@ const POOL_AUTOMATION_RUN_PATH = "/plugins/dsh-xdpool/automation/run";
 /** Set or clear one account's reserved-credit floor. */
 const POOL_CREDIT_RESERVE_PATH = "/plugins/dsh-xdpool/accounts/credit-reserve";
 /**
+* Estimated credit spend, per channel and per model.
+*
+* Derived from the pack's own token ledger, never from a credit counter — the pack
+* records tokens, and the vendor's balance is only visible when it is read again. The
+* arithmetic (tokens ÷ 1e6 × the model's published multiplier) and the honesty about
+* its error live in `credits.ts`.
+*
+* `?days=N` limits the window; the ledger keeps 90 days.
+*/
+const POOL_CREDITS_SPEND_PATH = "/plugins/dsh-xdpool/credits/spend";
+/**
 * Name the account to try first, or hand the choice back to the strategy.
 *
 * A route rather than a settings write for the reason the ignore list is a file:
@@ -5422,6 +5685,22 @@ const REGISTERED_CHANNELS = [
 		note: "手机号注册即送免费额度；每日积分由服务端自动发放，登录奖励需在「新手任务」领取",
 		login: "browser",
 		smsHint: true,
+		/**
+		* `credits: {}` is deliberate and does NOT mean "nothing to collect".
+		*
+		* Raccoon pays two different things and they arrive two different ways:
+		*
+		*   - the DAILY points are credited by the server on its own schedule, so
+		*     there is no check-in call to make. `credits.claimAll` answers "不支持每日
+		*     签到" for this channel, and that answer is correct;
+		*   - the DESKTOP LOGIN BONUS is a one-off, per account, and it is collectable
+		*     — through `onboarding.claim`, not through the daily claim.
+		*
+		* The empty object is what keeps the daily "Claim credits" button off this card
+		* (pressing it would only ever print that refusal). The login bonus has its own
+		* button, which the card draws for the channels in `ONBOARDING_CHANNELS`.
+		* `credits` staying present keeps the balance row on the card.
+		*/
 		credits: {}
 	},
 	{
@@ -18270,6 +18549,29 @@ function registerPoolStatusRoute(ctx, deps) {
 			}
 		});
 		/**
+		* Estimated credit spend, per channel.
+		*
+		* GET, `?days=N` optional. Read-only and cheap: the ledger roll-up is arithmetic
+		* over a file the pack already keeps, so the strip can refresh on every turn
+		* without touching an upstream.
+		*/
+		const disposeCreditsSpend = ctx.webServer.register({
+			kind: "exact",
+			path: POOL_CREDITS_SPEND_PATH,
+			handler: async (req, res) => {
+				if (req.method !== "GET") return json(res, 405, { error: "method not allowed" });
+				if (!loopbackOrigin(req)) return json(res, 403, { error: "origin-not-trusted" });
+				if (deps.creditsSpend === void 0) return json(res, 503, { error: "credit accounting is not available in this build" });
+				try {
+					const raw = new URL(req.url ?? "/", "http://127.0.0.1").searchParams.get("days");
+					const parsed = raw === null ? void 0 : Number(raw);
+					json(res, 200, await deps.creditsSpend(parsed === void 0 || !Number.isFinite(parsed) ? void 0 : Math.trunc(parsed)));
+				} catch (error) {
+					json(res, 500, { error: safeMessage(error) });
+				}
+			}
+		});
+		/**
 		* Replace the whole chain table.
 		*
 		* POST only, one table per request (see `POOL_COMBOS_SAVE_PATH`). The write
@@ -18325,6 +18627,7 @@ function registerPoolStatusRoute(ctx, deps) {
 			disposeRelay();
 			disposeCombosSave();
 			disposeCombos();
+			disposeCreditsSpend();
 			disposeChannels();
 			disposeAggregate();
 			disposeAggregateDiscover();
@@ -20668,6 +20971,328 @@ async function recoverFromContextOverrun(options) {
 	};
 }
 //#endregion
+//#region src/credits.ts
+/**
+* Coefficients by model id, as the billing gateway names them.
+*
+* Keys are lower-cased and matched case-insensitively, because the three sources that
+* name a model here (the pool catalog, the pack ledger, a channel listing) disagree on
+* casing: `deepseek-v4.1-flash` / `DeepSeek-V4.1-Flash`.
+*
+* The `(闲时)` suffix in the source table marks DeepSeek's off-peak price. It is used as
+* the plain rate: peak pricing is higher, so an estimate built on the off-peak figure
+* UNDERSTATES the bill, which is the safe direction for a "can I keep going" gauge.
+*/
+const RATE_TABLE = {
+	"deepseek-v4.1-flash": {
+		input: 14.29,
+		cache: .29,
+		output: 57.1
+	},
+	"space-bunny": {
+		input: 15,
+		cache: 3,
+		output: 60
+	},
+	"minimax-m3.1-flash": {
+		input: 28.57,
+		cache: 2.86,
+		output: 114.3
+	},
+	"glm-5.3-flash": {
+		input: 14.86,
+		cache: 4.29,
+		output: 52
+	},
+	"mimo-v2.6-pro": {
+		input: 85.71,
+		cache: .71,
+		output: 171.4
+	},
+	"hy4-preview": {
+		input: 142.86,
+		cache: 5.71,
+		output: 285.7
+	},
+	"step-5-preview": {
+		input: 120,
+		cache: 12,
+		output: 342.9
+	},
+	"deepseek-v4-pro": {
+		input: 257.14,
+		cache: 8.57,
+		output: 771.4
+	},
+	"glm-5.3": {
+		input: 160,
+		cache: 40,
+		output: 560
+	},
+	"glm-5.2": {
+		input: 160,
+		cache: 40,
+		output: 560
+	},
+	"kimi-k2.8-preview": {
+		input: 158,
+		cache: 41.43,
+		output: 655.7
+	},
+	"kimi-k3.1-pro": {
+		input: 315.71,
+		cache: 31.71,
+		output: 1651.4
+	},
+	"kimi-k3-1": {
+		input: 485.71,
+		cache: 48.57,
+		output: 2428.6
+	},
+	"kimi-k3": {
+		input: 485.71,
+		cache: 48.57,
+		output: 2428.6
+	}
+};
+/**
+* Tokens are frequently reported in a "total" form that already includes the cached
+* portion, while the pool's own ledger keeps them apart. Normalising here — rather than
+* at each call site — is what keeps one caller from double-counting.
+*/
+function cacheRateOf(model) {
+	const key = model.trim().toLowerCase();
+	if (key === "") return void 0;
+	const direct = RATE_TABLE[key];
+	if (direct !== void 0) return direct;
+	const tail = key.split("/").pop();
+	if (tail !== void 0 && tail !== key) {
+		const byTail = RATE_TABLE[tail];
+		if (byTail !== void 0) return byTail;
+	}
+	for (const candidate of Object.keys(RATE_TABLE)) if (key.startsWith(candidate) || key.endsWith(candidate)) return RATE_TABLE[candidate];
+}
+/**
+* Credits for one row, using the three-coefficient formula.
+*
+* Each term is divided by a million because the coefficients are per-million-token; the
+* sum is rounded to four decimals so a long tail of small requests accumulates into
+* something comparable without claiming precision nobody has.
+*/
+function creditsOf(inputTokens, cacheTokens, outputTokens, rates) {
+	if (rates === void 0) return void 0;
+	const fresh = Math.max(0, inputTokens);
+	const cached = Math.max(0, cacheTokens);
+	const out = Math.max(0, outputTokens);
+	const total = (fresh * rates.input + cached * rates.cache + out * rates.output) / 1e6;
+	return Math.round(total * 1e4) / 1e4;
+}
+/** Roll per-model rows up to one line per channel. */
+function totalsByChannel(rows) {
+	const byChannel = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const current = byChannel.get(row.channel) ?? {
+			channel: row.channel,
+			requests: 0,
+			inputTokens: 0,
+			cacheTokens: 0,
+			outputTokens: 0,
+			credits: 0,
+			unpricedModels: 0
+		};
+		current.requests += row.requests;
+		current.inputTokens += row.inputTokens;
+		current.cacheTokens += row.cacheTokens;
+		current.outputTokens += row.outputTokens;
+		if (row.credits === void 0) current.unpricedModels += 1;
+		else current.credits = Math.round((current.credits + row.credits) * 1e4) / 1e4;
+		byChannel.set(row.channel, current);
+	}
+	return [...byChannel.values()].sort((a, b) => b.credits - a.credits);
+}
+/**
+* The coefficients for a model, exported for the report.
+*
+* Returns undefined rather than zeros for an unknown model: "we do not know the price"
+* and "this was free" are different statements, and a zero would collapse them.
+*/
+function ratesFor(model) {
+	return cacheRateOf(model);
+}
+//#endregion
+//#region src/credit-report.ts
+/**
+* Read the pack's token ledger off disk and estimate credit spend per channel.
+*
+* WHY IT READS THE FILE INSTEAD OF CALLING THE PACK
+*
+* `usage.tokenLedgerHistory` exists, but it is reachable only through the pack's
+* browser-facing RPC (`/api/channel-pack`), which the host half does not speak — that
+* route is installed by the pack for the CARD. Reading `token-ledger.json` directly is
+* cheaper, needs no round trip, and works while the pack is still mounting.
+*
+* The file is a build artifact of another repository, so its shape is treated as
+* external and every level is validated before use: an unexpected shape must degrade
+* to "no data", never to a wrong number. The only thing relied on is the documented
+* shape — `{ days: { 'YYYY-MM-DD': { '<mode>|<channel>|<account>|<model>': stats } } }`
+* — and each key component is parsed positionally with a length check.
+*
+* WHAT IT DOES NOT DO
+*
+* It does not claim to know what the vendor charged. See `credits.ts` for the
+* arithmetic and for why the figure is labelled "estimated".
+*
+* @module dsh-xdpool/credit-report
+*/
+/**
+* Which ledger rows count as "the account pool spent this".
+*
+* The pack stamps every row with a `channel` of exactly two values:
+*
+*   - `direct`  — the pool (or a channel) was used by this plugin itself, which is the
+*                 DSH conversation spending pooled quota. This is what the strip reports;
+*   - `gateway` — the request arrived through the LAN relay, i.e. some OTHER device
+*                 using this machine as an OpenAI endpoint.
+*
+* Mixing them would make the strip answer a question nobody asked — "how much has my
+* whole household spent" — and would let a phone pointed at the relay inflate a number
+* the user reads as their own conversation. They are counted separately.
+*/
+const POOL_MODE = "direct";
+/**
+* Where the ledger lives, relative to the DSH home.
+*
+* Under `channel-pack/`, not at the top of the home — the pack owns its own directory
+* and this file is one of its artifacts. Reading `home/token-ledger.json` finds
+* nothing and reports an empty ledger, which looks exactly like "you have spent
+* nothing" rather than "this is looking in the wrong place".
+*/
+const LEDGER_FILE = join("channel-pack", "token-ledger.json");
+function numberOf(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/** `2026-11-07` minus N days, as the same string shape. */
+function daysAgoKey(days, now = /* @__PURE__ */ new Date()) {
+	const copy = new Date(now.getTime());
+	copy.setUTCDate(copy.getUTCDate() - days);
+	return copy.toISOString().slice(0, 10);
+}
+/** Split `mode|channel|account|model`, refusing anything that is not four parts. */
+function parseLedgerKey(key) {
+	const parts = key.split("|");
+	if (parts.length < 4) return void 0;
+	const mode = (parts[0] ?? "").trim();
+	const channel = (parts[1] ?? "").trim();
+	const model = (parts[3] ?? "").trim();
+	if (mode === "" || channel === "" || model === "") return void 0;
+	return {
+		mode,
+		channel,
+		model
+	};
+}
+/**
+* Build the report.
+*
+* `rateOf` resolves a model's multiplier from the channel's catalogue. It is a
+* callback rather than a table because the catalogue is the pack's live data — reading
+* it here would mean a second copy that drifts. Returning undefined for a model means
+* "no published rate", which the report counts separately instead of billing at zero.
+*/
+async function readCreditSpend(input) {
+	const empty = {
+		windowDays: input.days,
+		from: "",
+		to: "",
+		rows: [],
+		channels: [],
+		unreadable: 0,
+		gatewayRequests: 0,
+		empty: true
+	};
+	let text;
+	try {
+		text = await readFile(join(input.home, LEDGER_FILE), "utf8");
+	} catch {
+		return empty;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return empty;
+	}
+	const daysNode = parsed.days;
+	if (daysNode === null || typeof daysNode !== "object") return empty;
+	const earliest = input.days === void 0 ? void 0 : daysAgoKey(input.days, input.now);
+	const acc = /* @__PURE__ */ new Map();
+	let unreadable = 0;
+	let gatewayRequests = 0;
+	let sawAnyDay = false;
+	let from = "";
+	let to = "";
+	for (const [day, entries] of Object.entries(daysNode)) {
+		if (/^\d{4}-\d{2}-\d{2}$/u.test(day)) {
+			if (earliest !== void 0 && day < earliest) continue;
+			sawAnyDay = true;
+			if (from === "" || day < from) from = day;
+			if (to === "" || day > to) to = day;
+		} else continue;
+		if (entries === null || typeof entries !== "object") continue;
+		for (const [key, stats] of Object.entries(entries)) {
+			const named = parseLedgerKey(key);
+			if (named === void 0) {
+				unreadable += 1;
+				continue;
+			}
+			if (named.mode !== POOL_MODE) {
+				const entry = stats;
+				if (entry !== null && typeof entry === "object") gatewayRequests += numberOf(entry.requests);
+				continue;
+			}
+			if (stats === null || typeof stats !== "object") continue;
+			const entry = stats;
+			const id = `${named.channel}\u0000${named.model}`;
+			const current = acc.get(id) ?? {
+				channel: named.channel,
+				model: named.model,
+				requests: 0,
+				inputTokens: 0,
+				cacheTokens: 0,
+				outputTokens: 0
+			};
+			current.requests += numberOf(entry.requests);
+			current.inputTokens += numberOf(entry.inputTokens);
+			current.cacheTokens += numberOf(entry.cacheReadTokens);
+			current.outputTokens += numberOf(entry.outputTokens);
+			acc.set(id, current);
+		}
+	}
+	const rows = [...acc.values()].map((entry) => {
+		const rates = input.rateOf(entry.channel, entry.model);
+		return {
+			channel: entry.channel,
+			model: entry.model,
+			requests: entry.requests,
+			inputTokens: entry.inputTokens,
+			cacheTokens: entry.cacheTokens,
+			outputTokens: entry.outputTokens,
+			rates,
+			credits: creditsOf(entry.inputTokens, entry.cacheTokens, entry.outputTokens, rates)
+		};
+	}).sort((a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens));
+	return {
+		windowDays: input.days,
+		from: sawAnyDay ? from : "",
+		to: sawAnyDay ? to : "",
+		rows,
+		channels: totalsByChannel(rows),
+		unreadable,
+		gatewayRequests,
+		empty: !sawAnyDay
+	};
+}
+//#endregion
 //#region src/relay.ts
 /**
 * LAN relay: re-exposes the pool's loopback OpenAI shim on a LAN address, so a
@@ -20802,6 +21427,28 @@ function writeJson(res, status, code, message) {
 	res.end(body);
 }
 /**
+* Turn a bind failure into something the reader can act on.
+*
+* `listen EADDRINUSE: address already in use 127.0.0.1:8326` is accurate and useless.
+* The overwhelmingly common cause is not "another program stole the port" — it is a
+* previous DSH that has not finished exiting, still holding the relay it was serving.
+* The requested port and the old listener are the same, so the fix is either to wait,
+* or to pick a different port, and the message should say both.
+*
+* `EADDRNOTAVAIL` gets its own line because it means the machine has no such
+* interface, which is a different mistake from a busy port and sends the reader
+* looking in the wrong place if merged.
+*
+* The raw text is kept at the end rather than dropped: it is the only thing that can
+* be searched for, and a paraphrase that loses it is worse than no paraphrase.
+*/
+function explainBindFailure(raw, host, port) {
+	if (/EADDRINUSE/iu.test(raw)) return `端口 ${port} 已被占用（${host}）。最常见的原因是上一个 DSH 还没完全退出、仍占着这个网关端口：稍等几秒重试，或换一个端口后再打开。原始错误：${raw}`;
+	if (/EADDRNOTAVAIL/iu.test(raw)) return `本机没有这个绑定地址（${host}）。选 127.0.0.1 只允许本机访问；要让手机等其他设备连进来才选 0.0.0.0。原始错误：${raw}`;
+	if (/EACCES/iu.test(raw)) return `没有权限绑定端口 ${port}。1024 以下的端口通常需要管理员权限，换一个 1024 以上的端口即可。原始错误：${raw}`;
+	return raw;
+}
+/**
 * Build the relay.
 *
 * Nothing binds until {@link PoolRelay.ready} settles, so a port clash becomes a
@@ -20845,8 +21492,9 @@ function createPoolRelay(options) {
 	const start = (host, port) => new Promise((resolve) => {
 		const next = createServer(handle);
 		const fail = (error) => {
-			bindError = error instanceof Error ? error.message : String(error);
-			logger?.warn(`xdpool relay: cannot bind ${host}:${port} — ${bindError}`);
+			const raw = error instanceof Error ? error.message : String(error);
+			bindError = explainBindFailure(raw, host, port);
+			logger?.warn(`xdpool relay: cannot bind ${host}:${port} — ${raw}`);
 			next.close(() => resolve());
 		};
 		next.once("error", fail);
@@ -22145,6 +22793,67 @@ function apply(ctx, config = {}) {
 		roster: () => shim.roster(),
 		warn: (error) => ctx.logger.warn("dsh-xdpool: gateway roster failed", error)
 	});
+	/**
+	* Estimated credit spend, read from the pack's own token ledger.
+	*
+	* TWO rate sources, because the pool and the login channels price models
+	* differently and NEITHER publishes a rate through the ledger:
+	*
+	*   - a POOL model (`buddy`, `workbuddy`) carries `multiplier` on its catalog row,
+	*     which is the gateway's own `creditMultiplier`. The built-in fallback table
+	*     deliberately has none — a stale price is worse than no price — so this is
+	*     populated only once the live catalog has loaded;
+	*   - a LOGIN-CHANNEL model (`trae`, `zcode`, …) carries its rate in the DISPLAY NAME
+	*     the pack builds (`Hy3 · x0.05`), because `model.list` has no rate field at all.
+	*
+	* Checking only the second was wrong: it left every pool row unpriced, which reads as
+	* "the pool is free" — the opposite of the truth for the channel the user actually
+	* uses most.
+	*/
+	/**
+	* Estimated credit spend, read from the pack's own token ledger.
+	*
+	* The coefficients come from the table in `credits.ts`, measured against the live
+	* gateway — NOT from the `x0.11` figure the picker displays. That figure is a label;
+	* billing is three separate per-model coefficients (fresh input / cache read / output),
+	* and using the label as a flat rate understated a normal day by two orders of
+	* magnitude because it ignored the cache tier entirely.
+	*
+	* The pool's own catalog carries a `multiplier`, and it is deliberately NOT used for
+	* money: it is whatever the vendor chose to display, it moves with promotions, and the
+	* three-coefficient table is the only thing that reconciles against real charges.
+	*/
+	const creditSpend = async (days) => {
+		/**
+		* Channel model names, read from the pack's own listing — NOT from the gateway
+		* roster.
+		*
+		* `hostRoster()` returns only what the gateway SHARES, and a user typically shares
+		* one model. The ledger records every model the pool has ever served, so pricing off
+		* the roster left almost every channel row unpriced.
+		*/
+		let channelNames;
+		const rateOf = (channel, modelId) => {
+			const direct = ratesFor(modelId);
+			if (direct !== void 0) return direct;
+			const row = channelNames?.find((candidate) => candidate.channel === channel && candidate.modelId === modelId);
+			return row === void 0 ? void 0 : ratesFor(row.name);
+		};
+		try {
+			channelNames = (await channelLane.rows()).map((row) => ({
+				channel: row.channel,
+				modelId: row.modelId,
+				name: row.name
+			}));
+		} catch (error) {
+			ctx.logger?.warn?.("dsh-xdpool: channel model names unavailable for pricing:", error);
+		}
+		return await readCreditSpend({
+			home: dshHome(),
+			days,
+			rateOf
+		});
+	};
 	ctx.inject(["webServer"], (webCtx) => registerPoolStatusRoute(webCtx, {
 		pool: core.pool,
 		catalogs: core.catalogs,
@@ -22344,6 +23053,8 @@ function apply(ctx, config = {}) {
 			await aggregateCatalog.refresh();
 			return combosStatusOf(readAggregateSettingsSync(), aggregateCatalog, core.catalogs.cn.current(), await hostRoster());
 		},
+		/** Estimated credit spend per channel, for the composer strip. */
+		creditsSpend: async (days) => await creditSpend(days),
 		/**
 		* Relay state plus the gateway's model picker.
 		*