@linxin666/dsh-usage 0.3.23 → 0.4.0

package/lib/index.js

@@ -45,7 +45,7 @@ function mountOnce(packageName, fn) {
 	});
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-brand@0.1.5-rc.1_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-brand/lib/index.js
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-brand@0.1.7-rc.1_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-brand/lib/index.js
 /**
 * Duplicate-install-safe nominal primitive helpers.
 *
@@ -68,7 +68,7 @@ function brandString(value) {
 	return value;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-credentials@0.1.5-rc.1_@deepseek-ai+cordis@4.0.2_@deepseek-ai+dsh-inva_8353d2c97c08a345a5c3047263f2fe4a/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-credentials@0.1.7-rc.1_@deepseek-ai+cordis@4.0.4_@deepseek-ai+dsh-inva_9b80248df36b741e5eb76c73b242287a/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
 /**
 * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
 * *references* to secrets — environment-variable names — while providers own
@@ -149,6 +149,48 @@ function dshHome() {
 	return resolveDshHome();
 }
 //#endregion
+//#region src/host/http.ts
+/** Family-default JSON response headers; callers may append or override. */
+const JSON_HEADERS = {
+	"content-type": "application/json; charset=utf-8",
+	"referrer-policy": "no-referrer"
+};
+/**
+* Request init that asks a remote origin for an uncompressed body.
+*
+* The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
+* the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
+* Node's built-in `fetch()` reads. That cross-major wrapper drops the
+* `content-encoding` header and automatic decompression, so a plain fetch
+* resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
+* consumer can read. Every host fetch that parses a remote body must request
+* identity encoding. Caller headers survive; `accept-encoding` is forced to
+* `identity` because a caller value has no decoder behind it in this host.
+* @param init - the caller's request init (signal, headers, method, ...).
+* @returns a copy with `accept-encoding: identity` merged in.
+*/
+function withIdentityEncoding(init = {}) {
+	const headers = new Headers(init.headers);
+	headers.set("accept-encoding", "identity");
+	return {
+		...init,
+		headers
+	};
+}
+/**
+* Write one JSON response. Default headers are the family defaults
+* (content-type and referrer-policy); caller headers are appended or
+* override them.
+*/
+function writeJson(res, status, body, headers = {}) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		...JSON_HEADERS,
+		...headers
+	});
+	res.end(payload);
+}
+//#endregion
 //#region src/core/adapters.ts
 /** Parse a string/number into a finite number, else undefined. */
 function toNum(value) {
@@ -162,6 +204,10 @@ function toNum(value) {
 function str(value) {
 	return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
 }
+/** Clamp a provider percentage into the renderable 0-100 band. */
+function clampPercent(value) {
+	return Math.max(0, Math.min(100, value));
+}
 /** Format a number to a fixed 2-decimal display string. */
 function money(value) {
 	return value.toFixed(2);
@@ -294,7 +340,28 @@ const KIMI_CODING = {
 		}
 	}
 };
-/** GLM Coding Plan quota; auth is the RAW key without a Bearer prefix. */
+/**
+* GLM Coding Plan quota windows, keyed by the provider's own `unit` code
+* rather than by row position so an added or reordered limit cannot shift a
+* window's meaning: 3 = the rolling 5-hour window, 6 = the weekly window,
+* 5 = the monthly one. Two row kinds carry quota — `TOKENS_LIMIT` (token
+* plans) and `CREDIT_LIMIT` (credit plans, whose exact ratio is
+* `currentValue` / `usage`) — while `TIME_LIMIT` is the MCP request cap and
+* is not a plan window at all. Auth is the RAW key without a Bearer prefix.
+*/
+const GLM_UNIT_KEYS = {
+	3: "5h",
+	5: "month",
+	6: "week"
+};
+/** Percent from a credit row's exact ratio, else the provider's own percentage. */
+function glmCreditPercent(row) {
+	const used = toNum(row.currentValue);
+	const limit = toNum(row.usage);
+	if (used !== void 0 && limit !== void 0 && limit > 0) return clampPercent(used / limit * 100);
+	const percentage = toNum(row.percentage);
+	return percentage === void 0 ? void 0 : clampPercent(percentage);
+}
 function glmPlan(host, ids) {
 	return {
 		ids,
@@ -319,11 +386,17 @@ function glmPlan(host, ids) {
 				for (const entry of limits) {
 					if (typeof entry !== "object" || entry === null) continue;
 					const row = entry;
-					const unit = toNum(row.unit);
-					const percent = toNum(row.percentage);
+					const kind = str(row.type);
+					if (kind === "TIME_LIMIT") continue;
+					const key = GLM_UNIT_KEYS[toNum(row.unit) ?? NaN];
+					if (key === void 0) continue;
+					if (kind !== "TOKENS_LIMIT" && kind !== "CREDIT_LIMIT") continue;
 					windows.push({
-						key: unit === 3 ? "5h" : unit === 6 ? "week" : unit !== void 0 ? `unit-${unit}` : "window",
-						percent: percent === void 0 ? void 0 : Math.max(0, Math.min(100, percent)),
+						key,
+						percent: kind === "CREDIT_LIMIT" ? glmCreditPercent(row) : (() => {
+							const percentage = toNum(row.percentage);
+							return percentage === void 0 ? void 0 : clampPercent(percentage);
+						})(),
 						resetsAt: toIso(row.nextResetTime)
 					});
 				}
@@ -537,7 +610,7 @@ const PROVIDER_ADAPTERS = [
 	moonshotBalance("api.moonshot.ai", "USD", ["moonshotai"]),
 	KIMI_CODING,
 	glmPlan("open.bigmodel.cn", ["zai-coding-cn"]),
-	glmPlan("api.z.ai", ["zai-coding"]),
+	glmPlan("api.z.ai", ["zai", "zai-coding"]),
 	OPENCODE_GO,
 	minimaxPlan("api.minimaxi.com", ["minimax-cn"]),
 	minimaxPlan("api.minimax.io", ["minimax"]),
@@ -574,6 +647,34 @@ function providerErrorMessage(status, body) {
 	return `HTTP ${status}${message === void 0 ? "" : `: ${message.slice(0, 120)}`}`;
 }
 //#endregion
+//#region src/core/provider-routes.ts
+/**
+* Alias folding for the enumerated provider routes. Kept in core because the
+* rule is pure — the host enumerates routes and this decides which of two
+* routes serving one adapter family survives.
+* @module @linxin666/dsh-usage/core/provider-routes
+*/
+/**
+* Drop dormant catalog aliases that shadow a live route of the same adapter
+* family. The pi-ai catalog ships route keys the runtime serves nothing on
+* until a profile declares them: for DeepSeek the catalog entry `deepseek`
+* sits beside the llm-deepseek runtime route `deepseek-official`, and both
+* resolve the same credential (the family's `apiKeyEnv` fallback), so probing
+* and rendering both turns one account into two identical balance rows.
+*
+* A family keeps every live route it has — two configured profiles are two
+* real accounts, not aliases. A route with no adapter, or one whose family
+* has no live route at all, is returned untouched.
+*/
+function foldAliasRoutes(routes) {
+	return routes.filter((route) => {
+		if (route.live) return true;
+		const family = adapterFor(route.id);
+		if (family === void 0) return true;
+		return !routes.some((other) => other.live && adapterFor(other.id) === family);
+	});
+}
+//#endregion
 //#region src/core/pricing.ts
 /** The published peak windows: weekday 09:00-12:00 and 14:00-18:00. */
 const PEAK_WINDOWS = [{
@@ -856,112 +957,15 @@ function deserializeLedger(value) {
 /**
 * The dsh-usage host service: folds live session usage into the persistent
 * ledger, probes each configured provider's balance/coding-plan endpoint on
-* a poll cycle, and announces the current provider's status to the pet
-* bubble. Secrets stay in the host process; the browser only ever sees the
-* overview document.
+* a poll cycle, and serves the current provider's strip-ready view inside
+* the overview document. Secrets stay in the host process; the browser only
+* ever sees the overview document.
 * @module @linxin666/dsh-usage/host/usage-service
 */
-/** Source tag the plugin stamps onto pet announcements. */
-const USAGE_ANNOUNCE_SOURCE = "dsh-usage";
 /** Probe timeout per HTTP call. */
 const PROBE_TIMEOUT_MS = 1e4;
 /** Ledger flush debounce. */
 const FLUSH_DEBOUNCE_MS = 3e3;
-/** Currency symbols the bubble and section render inline; other codes render as `12.00 EUR`. */
-const CURRENCY_SYMBOLS = {
-	CNY: "¥",
-	USD: "$",
-	EUR: "€",
-	GBP: "£"
-};
-/** Format a balance for display: symbol prefix when known, code suffix otherwise. */
-function formatMoney(currency, totalBalance) {
-	const symbol = CURRENCY_SYMBOLS[currency.toUpperCase()];
-	if (symbol !== void 0) return symbol + totalBalance;
-	return `${totalBalance} ${currency.toUpperCase()}`;
-}
-/** Map a used percent to the announcement tone. */
-function planTone(percent) {
-	if (percent >= 90) return "low";
-	if (percent >= 70) return "warn";
-	return "ok";
-}
-/**
-* Build the raw pet announce payload for one provider snapshot, or
-* undefined when nothing worth announcing exists. Pure: every payload this
-* returns satisfies the pet's `parseAnnouncement` contract — plan
-* announcements require a numeric percent, so percent-less windows never
-* announce (the pet validator would silently drop them). A priced family
-* (DeepSeek) with spend today announces a cost bubble first; balance-only
-* families announce the balance; plan families announce their tightest
-* percent window.
-*/
-function buildAnnouncement(snapshot, context) {
-	const todayCost = context?.todayCost ?? 0;
-	if (todayCost > 0) {
-		const peak = context?.peak ?? false;
-		const noteParts = [peak ? "高峰时段 计价×2" : "空闲时段 计价减半", ...snapshot.balance !== void 0 ? [`余额 ${formatMoney(snapshot.balance.currency, snapshot.balance.totalBalance)}`] : []];
-		return {
-			kind: "cost",
-			title: snapshot.displayName,
-			amount: `今日 ${formatMoney("CNY", todayCost.toFixed(2))}`,
-			...noteParts.length > 0 ? { note: noteParts.join(" · ") } : {},
-			tone: peak ? "warn" : "ok"
-		};
-	}
-	if (snapshot.balance !== void 0) return {
-		kind: "balance",
-		title: snapshot.displayName,
-		amount: formatMoney(snapshot.balance.currency, snapshot.balance.totalBalance),
-		tone: "ok"
-	};
-	if (snapshot.plan === void 0) return void 0;
-	const window = snapshot.plan.windows.filter((entry) => typeof entry.percent === "number").sort((a, b) => (b.percent ?? 0) - (a.percent ?? 0))[0];
-	if (window === void 0 || window.percent === void 0) return void 0;
-	return {
-		kind: "plan",
-		title: snapshot.displayName,
-		percent: window.percent,
-		...window.resetsAt !== void 0 ? { resetAt: window.resetsAt } : {},
-		...snapshot.plan.planName !== void 0 ? { note: snapshot.plan.planName } : {},
-		tone: planTone(window.percent)
-	};
-}
-/**
-* Compact token-count display for the usage fallback bubble: `9805`,
-* `8.7万`, `1.2亿`. The host-authored bubble copy is zh (like every other
-* line this service speaks), so the magnitudes follow the zh convention.
-*/
-function formatTokens(count) {
-	const compact = (value) => {
-		const rounded = Math.round(value * 10) / 10;
-		return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
-	};
-	if (count >= 1e8) return compact(count / 1e8) + "亿";
-	if (count >= 1e4) return compact(count / 1e4) + "万";
-	return String(count);
-}
-/**
-* The usage fallback for the session's provider: today's token consumption
-* and call count, the one fact the ledger owns for every provider. Providers
-* without a readable balance/plan endpoint (relay stations, local runtimes,
-* token-plan vendors — and probeable providers whose probes are failing)
-* would otherwise leave the pet bubble permanently silent even while their
-* sessions run. Undefined when the provider has no usage today: a bubble
-* about nothing is noise, not information. Pure; the payload satisfies the
-* pet's `parseAnnouncement` contract.
-*/
-function buildLedgerAnnouncement(input) {
-	const total = totalTokens(input.totals);
-	if (input.totals.calls <= 0 || total <= 0) return void 0;
-	return {
-		kind: "cost",
-		title: input.displayName,
-		amount: `今日 ${formatTokens(total)} tokens`,
-		note: `${input.totals.calls} 次调用`,
-		tone: "ok"
-	};
-}
 /** Best-effort typed service read: absent services resolve to undefined at runtime. */
 function service(ctx, name) {
 	try {
@@ -1018,7 +1022,7 @@ var UsageService = class {
 	spendWatch;
 	/** Per-live-session route attribution (WeakMap: disposed sessions age out). */
 	sessionRoutes = /* @__PURE__ */ new WeakMap();
-	/** The most recent route seen this boot; the pet bubble follows it. */
+	/** The most recent route seen this boot; the sidebar strip and the header highlight follow it. */
 	current = { source: "default" };
 	sessionListenerDisposer;
 	pollTimer;
@@ -1031,7 +1035,6 @@ var UsageService = class {
 	/** True once loadPersisted finished; nothing may overwrite the files before that. */
 	loaded = false;
 	disposed = false;
-	lastSignature;
 	/** Last prune guard: once per local day, and whenever retention shrinks. */
 	lastPrune;
 	constructor(ctx, options) {
@@ -1049,8 +1052,9 @@ var UsageService = class {
 	}
 	/**
 	* Stop timers and flush pending ledger writes. The returned promise
-	* resolves after the final flush lands, so a successor instance (quick
-	* disable → enable) can serialize its first load behind it.
+	* resolves after the final flush lands, so a successor instance (the Host
+	* reloads the profile row on a config change) can serialize its first load
+	* behind it.
 	*/
 	stop() {
 		this.disposed = true;
@@ -1059,7 +1063,7 @@ var UsageService = class {
 		this.sessionListenerDisposer?.();
 		return this.flushLedger();
 	}
-	/** Re-apply options live (settings change); retention shrink prunes now. */
+	/** Re-apply options to this running instance; retention shrink prunes now. */
 	applyOptions(options) {
 		this.options = options;
 		this.pruneIfNeeded();
@@ -1098,7 +1102,7 @@ var UsageService = class {
 		return {
 			updatedAt: Date.now(),
 			providers,
-			current: { ...this.current },
+			current: this.currentView(),
 			usage: {
 				today: this.daySummary(todayKey),
 				days: days.map((date) => {
@@ -1126,6 +1130,33 @@ var UsageService = class {
 			}
 		};
 	}
+	/**
+	* The strip-ready current-provider view: the resolved display name plus
+	* today's ledger totals for the provider's adapter family (the route
+	* itself when adapter-less). `today` is absent on a day without usage —
+	* a strip about nothing is noise, not information.
+	*/
+	currentView() {
+		const provider = this.current.provider;
+		if (provider === void 0) return { ...this.current };
+		let snapshot = this.snapshots.get(provider);
+		if (snapshot === void 0) {
+			const family = adapterFor(provider);
+			if (family !== void 0) {
+				for (const [id, candidate] of this.snapshots) if (adapterFor(id) === family) {
+					snapshot = candidate;
+					break;
+				}
+			}
+		}
+		const displayName = snapshot?.displayName ?? this.routeDisplayName(provider);
+		const today = this.familyUsageToday(provider);
+		return {
+			...this.current,
+			displayName,
+			...today.calls > 0 && totalTokens(today) > 0 ? { today } : {}
+		};
+	}
 	/** One local day aggregated per provider. */
 	daySummary(dateKey) {
 		const { totals, providers } = summarizeDays([this.ledger.days[dateKey] ?? {}]);
@@ -1135,17 +1166,17 @@ var UsageService = class {
 			providers
 		};
 	}
-	/** Today's ledger spend for one provider's adapter family (0 when unpriced). */
-	familyCostToday(provider) {
+	/**
+	* Today's ledger totals for one provider's adapter family — the exact
+	* route when adapter-less, the merged family otherwise, so aliased routes
+	* of one account (the deepseek catalog id and its runtime alias) fold
+	* together.
+	*/
+	familyUsageToday(provider) {
 		const family = adapterFor(provider);
-		if (family === void 0) return 0;
-		let cost = 0;
-		for (const row of this.daySummary(localDateKey(Date.now())).providers) if (adapterFor(row.provider) === family) cost += row.totals.cost;
-		return cost;
-	}
-	/** Today's ledger totals for one provider route (the exact id, not the family). */
-	providerUsageToday(provider) {
-		return this.daySummary(localDateKey(Date.now())).providers.find((entry) => entry.provider === provider)?.totals ?? emptyTotals();
+		let merged = emptyTotals();
+		for (const row of this.daySummary(localDateKey(Date.now())).providers) if (family === void 0 ? row.provider === provider : adapterFor(row.provider) === family) merged = addTotals(merged, row.totals);
+		return merged;
 	}
 	/**
 	* Accrue the official DeepSeek family's real spend from observed CNY
@@ -1177,7 +1208,7 @@ var UsageService = class {
 	/**
 	* The display name for a route key: the LLM runtime's first, then the
 	* adapter's, then the id itself — the snapshot may not exist for
-	* adapter-less routes, yet the bubble still needs a legible title.
+	* adapter-less routes, yet the sidebar strip still needs a legible title.
 	*/
 	routeDisplayName(provider) {
 		return this.listProviderRoutes().find((entry) => entry.id === provider)?.displayName || adapterFor(provider)?.displayName || provider;
@@ -1326,7 +1357,7 @@ var UsageService = class {
 		}, delayMs);
 	}
 	/**
-	* One poll cycle: enumerate routes, resolve credentials, probe, announce.
+	* One poll cycle: enumerate routes, resolve credentials, probe.
 	* A call while a cycle is already running joins that cycle instead of
 	* returning immediately, so a manual refresh always waits for real probes.
 	*/
@@ -1350,7 +1381,6 @@ var UsageService = class {
 				if (this.disposed) return;
 				this.accrueDeepSeekSpend();
 				await this.persistSnapshots();
-				this.announceCurrent();
 			} finally {
 				this.pollInFlight = false;
 				this.pollPromise = void 0;
@@ -1359,17 +1389,28 @@ var UsageService = class {
 		this.pollPromise = cycle;
 		return cycle;
 	}
+	/**
+	* Every route the service probes and renders: the runtime's live providers
+	* plus the configurable directory's catalog entries, then alias-folded so a
+	* dormant catalog entry cannot shadow the live route of the same adapter
+	* family (see foldAliasRoutes).
+	*/
 	listProviderRoutes() {
 		const routes = /* @__PURE__ */ new Map();
 		const runtime = service(this.ctx, "llm");
 		if (runtime !== void 0) try {
-			for (const provider of runtime.listProviders()) if (provider.id !== "") routes.set(provider.id, provider.name);
-			for (const provider of runtime.listConfigurableProviders()) if (!routes.has(provider.provider)) routes.set(provider.provider, provider.displayName);
+			for (const provider of runtime.listProviders()) if (provider.id !== "") routes.set(provider.id, {
+				id: provider.id,
+				displayName: provider.name,
+				live: true
+			});
+			for (const provider of runtime.listConfigurableProviders()) if (!routes.has(provider.provider)) routes.set(provider.provider, {
+				id: provider.provider,
+				displayName: provider.displayName,
+				live: false
+			});
 		} catch {}
-		return [...routes].map(([id, displayName]) => ({
-			id,
-			displayName
-		}));
+		return foldAliasRoutes([...routes.values()]);
 	}
 	async probeRoute(route, adapter) {
 		const credential = await this.resolveCredential(route.id);
@@ -1399,10 +1440,10 @@ var UsageService = class {
 					apiKey: credential.key,
 					...credential.accountId !== void 0 ? { accountId: credential.accountId } : {}
 				});
-				const response = await fetch(spec.url, {
+				const response = await fetch(spec.url, withIdentityEncoding({
 					headers: spec.headers,
 					signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
-				});
+				}));
 				const body = await response.json().catch(() => void 0);
 				if (!response.ok) throw new Error(providerErrorMessage(response.status, body));
 				const parsed = half.parse(response.status, body);
@@ -1486,66 +1527,6 @@ var UsageService = class {
 	deepseekApiKeyEnv() {
 		return readNamespace(this.ctx, "llm-deepseek")?.apiKeyEnv ?? "DEEPSEEK_API_KEY";
 	}
-	/**
-	* Announce the current provider's spend, balance, or plan usage to the pet.
-	* In `change` mode only meaningful value changes re-announce; `off` skips.
-	* The TTL rides the poll interval (bubble_mode `always` re-announces every
-	* cycle, so a TTL of two cycles + margin keeps the bubble continuous
-	* across polls; the pet contract caps the ceiling). A route id the
-	* catalogs spell differently than the snapshot keys falls back to its
-	* adapter family's snapshot. When the provider has no announceable probe
-	* fact (no adapter, failing probes, percent-less windows) the bubble falls
-	* back to the provider's today ledger usage, and with neither fact nor
-	* usage it stays silent. Fully guarded: a malformed snapshot or a failing
-	* pet service must never break the poll loop, and a disposed service never
-	* announces.
-	*/
-	announceCurrent() {
-		if (this.disposed || this.options.bubbleMode === "off") return;
-		try {
-			let provider = this.current.provider;
-			if (provider === void 0) {
-				const fallback = readNamespace(this.ctx, "agent-default-model");
-				if (fallback?.provider !== void 0) {
-					provider = fallback.provider;
-					this.current = {
-						provider: fallback.provider,
-						model: fallback.model,
-						source: "default"
-					};
-				} else return;
-			}
-			let snapshot = this.snapshots.get(provider);
-			if (snapshot === void 0) {
-				const family = adapterFor(provider);
-				if (family !== void 0) {
-					for (const [id, candidate] of this.snapshots) if (adapterFor(id) === family) {
-						snapshot = candidate;
-						break;
-					}
-				}
-			}
-			const displayName = snapshot?.displayName ?? this.routeDisplayName(provider);
-			let announcement = snapshot !== void 0 ? buildAnnouncement(snapshot, {
-				todayCost: this.familyCostToday(provider),
-				peak: deepseekPeriodAt(Date.now()).peak
-			}) : void 0;
-			if (announcement === void 0) announcement = buildLedgerAnnouncement({
-				displayName,
-				totals: this.providerUsageToday(provider)
-			});
-			if (announcement === void 0) return;
-			const signature = JSON.stringify(announcement);
-			if (this.options.bubbleMode === "change" && signature === this.lastSignature) return;
-			this.lastSignature = signature;
-			const ttlMs = Math.min(72e5, this.options.pollIntervalSec * 2e3 + 3e4);
-			service(this.ctx, "pet")?.announce({
-				source: USAGE_ANNOUNCE_SOURCE,
-				ttlMs,
-				...announcement
-			});
-		} catch {}
-	}
 };
 //#endregion
 //#region src/host/loopback.ts
@@ -1593,38 +1574,50 @@ function isLoopbackRequest(request) {
 	}
 }
 //#endregion
-//#region src/host/http.ts
-/** Family-default JSON response headers; callers may append or override. */
-const JSON_HEADERS = {
-	"content-type": "application/json; charset=utf-8",
-	"referrer-policy": "no-referrer"
-};
+//#region src/host/pair-access.ts
 /**
-* Write one JSON response. Default headers are the family defaults
-* (content-type and referrer-policy); caller headers are appended or
-* override them.
+* Whether this request may enter the plugin's host routes.
+* @param ctx - host context; may expose remoteWebUiPairing.
+* @param request - the incoming HTTP request.
+* @returns true for loopback, or a live paired-device cookie.
 */
-function writeJson(res, status, body, headers = {}) {
-	const payload = JSON.stringify(body);
-	res.writeHead(status, {
-		...JSON_HEADERS,
-		...headers
-	});
-	res.end(payload);
+function isPairedOrLoopbackAllowed(ctx, request) {
+	if (isLoopbackRequest(request)) return true;
+	const fromGet = typeof ctx.get === "function" ? ctx.get("remoteWebUiPairing", false) : void 0;
+	return (isPairingAccess(fromGet) ? fromGet : ctx.remoteWebUiPairing)?.isPairedDevice(request) === true;
+}
+function isPairingAccess(value) {
+	return value !== void 0 && value !== null && typeof value.isPairedDevice === "function";
+}
+//#endregion
+//#region src/host/access.ts
+/**
+* Whether this request may read the usage overview or trigger a refresh.
+* @param ctx - host context; may expose remoteWebUiPairing.
+* @param request - the incoming HTTP request.
+* @returns true for loopback, or a live paired-device cookie.
+*/
+function isUsageAllowed(ctx, request) {
+	return isPairedOrLoopbackAllowed(ctx, request);
 }
 //#endregion
 //#region src/host/routes.ts
 /**
-* Loopback-fenced overview route: provider balances, plan quotas, and token
-* usage totals. Personal account data, so the loopback fence mirrors
-* dsh-perf's stats surface; the browser runs on the same machine.
+* Overview route: provider balances, plan quotas, and token usage totals.
+* Personal account data behind the family trust fence — loopback always
+* passes, and a live paired-device cookie passes too when remote-web-ui is
+* loaded (issue #1592: the sidebar usage panel reads this from a paired LAN
+* browser); every unpaired LAN request keeps its 403.
+* @param ctx - host context; may expose remoteWebUiPairing.
+* @param service - the usage service.
+* @returns the route.
 */
-function makeUsageOverviewRoute(service) {
+function makeUsageOverviewRoute(ctx, service) {
 	return {
 		kind: "exact",
 		path: "/api/dsh-usage/overview",
 		handler: async (req, res) => {
-			if (!isLoopbackRequest(req)) {
+			if (!isUsageAllowed(ctx, req)) {
 				writeJson(res, 403, {
 					ok: false,
 					error: "forbidden: loopback-only"
@@ -1636,15 +1629,18 @@ function makeUsageOverviewRoute(service) {
 	};
 }
 /**
-* Loopback-fenced manual refresh: forces one probe cycle now and answers
-* with the fresh overview.
+* Manual refresh: forces one probe cycle now and answers with the fresh
+* overview. Same trust fence as the overview route.
+* @param ctx - host context; may expose remoteWebUiPairing.
+* @param service - the usage service.
+* @returns the route.
 */
-function makeUsageRefreshRoute(service) {
+function makeUsageRefreshRoute(ctx, service) {
 	return {
 		kind: "exact",
 		path: "/api/dsh-usage/refresh",
 		handler: async (req, res) => {
-			if (!isLoopbackRequest(req)) {
+			if (!isUsageAllowed(ctx, req)) {
 				writeJson(res, 403, {
 					ok: false,
 					error: "forbidden: loopback-only"
@@ -1675,78 +1671,69 @@ function makeUsageRefreshRoute(service) {
 //#region src/index.ts
 const name = "dsh-usage";
 const inject = ["webServer"];
+/**
+* Family settings namespace this row serves. Since 0.1.7 the settings surface
+* addresses one form per profile entry id and the Host generates this row's
+* page from the Config schema below, so the namespace is only the alias the
+* family settings bridge (dsh-web-settings) resolves onto this row's entry id.
+*/
 const USAGE_SETTINGS_NAMESPACE = "dsh-usage";
 const Config = z.object({
 	enabled: z.boolean().default(true),
 	pollIntervalSec: z.number().min(30).max(3600).default(60),
-	bubbleMode: z.string().default("always"),
 	retainDays: z.number().min(7).max(730).default(180)
 });
 function resolveConfig(config) {
-	const bubbleMode = config?.bubbleMode === "change" || config?.bubbleMode === "off" ? config.bubbleMode : "always";
 	return {
 		enabled: config?.enabled ?? true,
 		pollIntervalSec: typeof config?.pollIntervalSec === "number" ? config.pollIntervalSec : 60,
-		bubbleMode,
 		retainDays: typeof config?.retainDays === "number" ? config.retainDays : 180
 	};
 }
+/**
+* Tail of the process-wide flush chain; undefined while no predecessor's final
+* ledger flush is still in flight. The Host reloads this profile row when its
+* configuration changes, so a successor activation is a dispose + apply pair in
+* the same process: its first ledger load must serialize behind its
+* predecessor's final write (and behind the reloads before that one).
+*/
+let pendingStop;
+/**
+* Host body. The plugin's own Config schema above is the settings document the
+* 0.1.7 Host serves for this row; the effective config arrives here as the
+* `config` argument the Loader resolved and the Host reloads the row when the
+* user saves a change, so nothing in this body observes or writes settings.
+* @param ctx - host root context.
+* @param config - the row's resolved configuration.
+*/
 const apply = mountOnce("@linxin666/dsh-usage", (ctx, config) => {
-	let source = () => config ?? {};
+	const value = resolveConfig(config);
+	if (!value.enabled) return;
+	let live = true;
 	let service;
-	let pendingStop;
 	let disposeRoutes;
-	const rearm = () => {
-		const value = resolveConfig(source());
-		if (!value.enabled) {
-			pendingStop = service?.stop();
-			service = void 0;
-			disposeRoutes?.();
-			disposeRoutes = void 0;
-			return;
-		}
-		if (service === void 0) {
-			const next = new UsageService(ctx, value);
-			service = next;
-			const begin = () => {
-				if (service !== next) return;
-				next.start();
-				const disposers = [makeUsageOverviewRoute(next), makeUsageRefreshRoute(next)].map((route) => ctx.webServer.register(route));
-				disposeRoutes = () => {
-					for (const dispose of disposers) try {
-						dispose();
-					} catch {}
-				};
-			};
-			if (pendingStop !== void 0) pendingStop.then(begin, begin);
-			else begin();
-		} else service.applyOptions(value);
+	const begin = () => {
+		if (!live) return;
+		const next = new UsageService(ctx, value);
+		service = next;
+		next.start();
+		const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageRefreshRoute(ctx, next)].map((route) => ctx.webServer.register(route));
+		disposeRoutes = () => {
+			for (const dispose of disposers) try {
+				dispose();
+			} catch {}
+		};
 	};
-	ctx.inject(["settings"], (settingsCtx) => {
-		try {
-			if (typeof settingsCtx.settings?.installSection === "function") settingsCtx.settings.installSection(ctx, USAGE_SETTINGS_NAMESPACE, Config, config ?? {}, {
-				setSource: (next) => {
-					source = next;
-					rearm();
-				},
-				onChange: rearm
-			});
-			else if (typeof settingsCtx.settings?.register === "function") {
-				const scope = settingsCtx.settings.register(USAGE_SETTINGS_NAMESPACE, Config, { base: config ?? {} });
-				source = () => scope?.get?.() ?? config ?? {};
-				scope?.watch?.(() => {
-					rearm();
-				});
-				rearm();
-			}
-		} catch {}
-	});
 	ctx.effect(() => {
-		rearm();
+		if (pendingStop === void 0) begin();
+		else pendingStop = pendingStop.then(begin, begin).then(() => void 0);
 		return () => {
+			live = false;
 			disposeRoutes?.();
-			service?.stop();
+			disposeRoutes = void 0;
+			const stopping = service?.stop();
 			service = void 0;
+			if (stopping !== void 0) pendingStop = (pendingStop ?? Promise.resolve()).then(() => stopping);
 		};
 	}, "dsh-usage: runtime");
 });