@ychris12138/dsh-usage-stats 0.3.1 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # dsh-usage-stats
 
-<!-- stable-version: 0.3.1 -->
+<!-- stable-version: 0.3.2 -->
 
 [![GitHub Release](https://img.shields.io/github/v/release/Ychris12138/dsh-usage-stats?display_name=tag&sort=semver&color=1f6feb)](https://github.com/Ychris12138/dsh-usage-stats/releases/latest)
 [![CI](https://github.com/Ychris12138/dsh-usage-stats/actions/workflows/ci.yml/badge.svg)](https://github.com/Ychris12138/dsh-usage-stats/actions/workflows/ci.yml)
@@ -39,7 +39,7 @@ Provider balances, subscription quotas, and token-usage analytics for the DeepSe
 稳定版优先安装 npm 上的精确版本；这也是 DSH Desktop Market 使用的同一个包：
 
 ```bash
-dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.1"
+dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.2"
 ```
 
 只有测试尚未发布的 source/RC 时才使用 `dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"`。GitHub `main` 可能领先 npm stable，不应把 source 安装当作市场安装验收。
@@ -53,7 +53,7 @@ dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.1"
 - `catalog/catalog-source.json` — 来源 manifest（`catalog-source.schema.json` v1.0.0）
 - `catalog/v1/plugins.json` — 标准 provider page（`catalog-provider-page.schema.json` v1.0.0）
 
-**使用前提（重要）**：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。`dsh-usage-stats` 这个 npm 名已被其他项目占用，因此目录条目身份使用 `@ychris12138/dsh-usage-stats`。当前 stable/catalog 版本是 `0.3.1`；每个新版本都按以下顺序发布：
+**使用前提（重要）**：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。`dsh-usage-stats` 这个 npm 名已被其他项目占用，因此目录条目身份使用 `@ychris12138/dsh-usage-stats`。当前 stable/catalog 版本是 `0.3.2`；每个新版本都按以下顺序发布：
 
 1. 运行 `npm run release:sync -- <version>` 同步 `package.json` / `package-lock.json` / `catalog/v1/plugins.json`，再由 `npm run check:release` 阻止身份或版本漂移。
 2. 发布 scoped 公共包：`npm publish --access public`。
@@ -349,7 +349,7 @@ Constraints:
 
 Procedure:
 1. Confirm node, npx, and dsh are available.
-2. Prefer the exact npm stable used by Desktop Market: `dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.1"` (or update the existing scoped package).
+2. Prefer the exact npm stable used by Desktop Market: `dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.2"` (or update the existing scoped package).
 3. Use `github:Ychris12138/dsh-usage-stats` only when I explicitly ask to test unreleased source/RC code.
 4. If dsh plugin is unavailable, use the compatible source installer only with my approval: `npx --yes github:Ychris12138/dsh-usage-stats`.
 5. Do not combine bundle installation with an existing manual dsh-usage-stats Cordis entry.
@@ -444,7 +444,7 @@ node scripts/check-balance.mjs
 
 ## 兼容性与致谢 / Compatibility & credits
 
-当前 npm stable 为 `0.3.1`；`v0.3.1` 的完整发布门禁见 [`docs/release-checklist.md`](docs/release-checklist.md)，变更摘要见 [`docs/release-notes-v0.3.1.md`](docs/release-notes-v0.3.1.md)。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。
+当前 npm stable 为 `0.3.2`；`v0.3.2` 的完整发布门禁见 [`docs/release-checklist.md`](docs/release-checklist.md)，变更摘要见 [`docs/release-notes-v0.3.2.md`](docs/release-notes-v0.3.2.md)。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。
 
 `display.currentSessionPill` 作为 v0.3.0 legacy boolean 配置键继续被接受，避免旧配置导致启动失败；当前客户端不再注册任何 composer UI，因此该键不再产生可见效果。`session-context` 服务端 API 暂时保留原有响应语义，供 v0.3.0 API compatibility 与后续集成使用。
 

package/docs/release-checklist.md

@@ -46,6 +46,13 @@ npm pack --json
 
 ## 5. Real DSH release-candidate regression
 
+### v0.3.2-specific gates
+
+- [ ] Current DSH sessions use the public `seq` / `snapshotEvents()` API; no current-session path accesses the removed `session.events` property.
+- [ ] Legacy sessions exposing `seq` plus an `events` array, but no `snapshotEvents()`, remain supported.
+- [ ] UI steady state performs zero persisted `listSnapshots`, zero persisted `readFrom`, zero unchanged aggregate rebuilds, and zero unchanged cache writes.
+- [ ] Background refresh skips `readFrom` and cache writes for unchanged revisions, uses incremental reads for changed revisions, and full-refolds truncation or rewrite cases.
+
 - [ ] Test the latest supported `@deepseek-ai/dsh` Desktop/Web release candidate with an isolated profile.
 - [ ] Confirm DSH starts without `Failed to load plugins` or loader identity errors.
 - [ ] Confirm client bundle load and that `sidebar.footer.action` is the only extension point registered by dsh-usage-stats; verify panel open/close, provider switching, cost/budget states, and manual Retry.
@@ -61,8 +68,8 @@ npm pack --json
 Do not run this section until every release-candidate gate above passes and the maintainer approves preparing the release commit.
 
 - [ ] Create a release branch from the reviewed `main` at `RC_BASE_SHA`.
-- [ ] Run `npm run release:sync -- 0.3.1` once to update `package.json`, `package-lock.json`, the Community Market catalog, and documented stable-version references together.
-- [ ] Confirm the v0.3.1 release notes use final stable wording, preserve the historical v0.3.0 notes, and do not claim #84 fixed or include #88 behavior.
+- [ ] Run `npm run release:sync -- 0.3.2` once to update `package.json`, `package-lock.json`, the Community Market catalog, and documented stable-version references together.
+- [ ] Confirm the v0.3.2 release notes use final stable wording, preserve the historical v0.3.0/v0.3.1 notes, and do not claim #84 fixed or include #88 behavior.
 - [ ] Run the release gates again against the synchronized version:
 
 ```bash
@@ -71,20 +78,20 @@ npm test
 npm pack --json
 ```
 
-- [ ] Inspect the final pack manifest, then commit all version/release metadata changes with `chore: prepare v0.3.1 release`.
+- [ ] Inspect the final pack manifest, then commit all version/release metadata changes with `chore: prepare v0.3.2 release`.
 - [ ] Record that commit as `RELEASE_SHA`; this replaces `RC_BASE_SHA` as the only publish/tag identity.
 - [ ] Confirm the working tree is clean and `HEAD` equals `RELEASE_SHA`.
 - [ ] Confirm the committed package version, not merely the working-tree version:
 
 ```bash
-test "$(git show "$RELEASE_SHA:package.json" | jq -r .version)" = "0.3.1"
+test "$(git show "$RELEASE_SHA:package.json" | jq -r .version)" = "0.3.2"
 ```
 
 The release invariant is:
 
 ```text
 npm published source commit
-== v0.3.1 tag commit
+== v0.3.2 tag commit
 == GitHub Release commit
 == package/catalog version commit
 == RELEASE_SHA
@@ -98,14 +105,14 @@ Do not run this section until the immutable release commit exists and the mainta
 - [ ] From a clean checkout/worktree at exactly `RELEASE_SHA`, run `npm publish --access public --registry=https://registry.npmjs.org/`.
 - [ ] `npm view "@ychris12138/dsh-usage-stats" version --registry=https://registry.npmjs.org/` equals the target version.
 - [ ] Merge or push the release commit to `main` according to the chosen branch workflow; verify `main` contains the exact `RELEASE_SHA` without recreating the release changes.
-- [ ] Only after npm and `main` verification: create the signed/annotated `v0.3.1` tag pointing explicitly to `RELEASE_SHA`.
+- [ ] Only after npm and `main` verification: create the signed/annotated `v0.3.2` tag pointing explicitly to `RELEASE_SHA`.
 - [ ] Verify the tag resolves to the published source commit:
 
 ```bash
-test "$(git rev-parse v0.3.1^{commit})" = "$RELEASE_SHA"
+test "$(git rev-parse v0.3.2^{commit})" = "$RELEASE_SHA"
 ```
 
-- [ ] Create the GitHub Release from `v0.3.1`; verify it resolves to `RELEASE_SHA`.
+- [ ] Create the GitHub Release from `v0.3.2`; verify it resolves to `RELEASE_SHA`.
 - [ ] Verify the public Pages `catalog-source.json` and `/v1/plugins` response content type, package name, and exact version.
 - [ ] Install the exact npm version through DSH Desktop Community Market and restart the host.
 - [ ] Close the npm/market release issue only after the Desktop Market installation succeeds.

package/docs/release-notes-v0.3.2.md

@@ -0,0 +1,36 @@
+# v0.3.2 release notes
+
+`v0.3.2` is a focused maintenance release for current DSH session compatibility and lower steady-state usage aggregation overhead.
+
+## Highlights
+
+### Current DSH Session API compatibility
+
+- Fixes #95 for DSH builds where the public `Session.events` array has been replaced by `seq` and `snapshotEvents()`.
+- Current DSH sessions now use the formal `seq` / `snapshotEvents(fromSeq)` API and continue folding only the live event tail.
+- Older DSH session objects without `snapshotEvents()` retain the legacy `events` fallback.
+- Compatibility is capability-based rather than tied to a DSH version string.
+- Preserves live-log shrink recovery and conservative live/persisted refolding semantics.
+
+### Lower usage polling overhead
+
+- Fixes #94 by separating high-frequency UI usage reads from persisted archive refreshes.
+- Ordinary `/usage` requests fold live-session tails and reuse cached persisted aggregates instead of enumerating every archived session.
+- Persisted archive scanning remains on the existing background refresh path and explicit export paths.
+- Unchanged collections no longer rebuild global aggregates or rewrite `usage-stats-cache.json`.
+- Persisted sessions with unchanged revision tokens perform no event reads.
+- A changed persisted revision still uses the existing incremental cursor logic, with full refolding retained for truncation or rewrite recovery.
+- Scan-mode single-flight guarantees that a required full persisted refresh cannot be satisfied accidentally by an in-flight live-only request.
+
+## Compatibility and non-features
+
+- No frontend polling interval change and no additional timer or polling loop.
+- No pricing-rule or billing-semantics changes.
+- Pricing/provider fingerprint changes still invalidate and persist derived billing state safely.
+- No private JSONL/zstd reader or plugin-owned persistence index.
+- No attempt to optimize live-to-persisted transitions by trusting the previous live fold.
+- No DSH `sessionProjectionCache` migration or modification.
+- No cold-session eviction or bounded-cache redesign.
+- No provider or composer UI changes.
+- No #84 quota-precision change and no #93 feature work is included in this release.
+- JSONL suffix reads remain an upstream DSH concern; a changed large archive may still require the host persistence backend to decode more data than the logical suffix.

package/lib/index.js

@@ -176,6 +176,37 @@ let loadedCache = null;
 let loadPromise = null;
 let inflight = null;
 
+// Runtime-only cache bookkeeping. Nothing in this WeakMap is serialized to
+// disk: the on-disk schema remains CACHE_VERSION=5. Keeping the aggregate and
+// dirty flags out of the persisted shape also means old cache files remain
+// valid while hot UI reads can skip redundant work.
+const cacheRuntime = new WeakMap();
+
+function runtimeOf(cache) {
+	let runtime = cacheRuntime.get(cache);
+	if (runtime === void 0) {
+		runtime = {
+			dirty: false,
+			aggregate: null,
+			aggregateDirty: true
+		};
+		cacheRuntime.set(cache, runtime);
+	}
+	return runtime;
+}
+
+function markCacheChanged(cache) {
+	const runtime = runtimeOf(cache);
+	runtime.dirty = true;
+	runtime.aggregateDirty = true;
+}
+
+function diagnostic(ctx, name) {
+	const stats = ctx?.__usageStatsDiagnostics;
+	if (stats === null || typeof stats !== "object") return;
+	stats[name] = (stats[name] ?? 0) + 1;
+}
+
 /** Serialize one session's fold state (Maps → plain objects). */
 function serializeSession(state) {
 	const days = {};
@@ -309,6 +340,7 @@ function parsePricingIdentityCutoffs(raw) {
 }
 
 function freshCache(pricingFingerprintValue, previous = null, transitionAt = Date.now()) {
+	const fingerprintChanged = previous !== null && previous.pricingFingerprint !== pricingFingerprintValue;
 	const pricingIdentityCutoffs = parsePricingIdentityCutoffs(previous?.pricingIdentityCutoffs);
 	let pricingIdentityCutoffAll = Number.isFinite(previous?.pricingIdentityCutoffAll) && previous.pricingIdentityCutoffAll >= 0
 		? previous.pricingIdentityCutoffAll
@@ -318,13 +350,19 @@ function freshCache(pricingFingerprintValue, previous = null, transitionAt = Dat
 		if (changedRoutes === null) pricingIdentityCutoffAll = Math.max(pricingIdentityCutoffAll ?? 0, transitionAt);
 		else for (const routeId of changedRoutes) pricingIdentityCutoffs[routeId] = Math.max(pricingIdentityCutoffs[routeId] ?? 0, transitionAt);
 	}
-	return {
+	const cache = {
 		version: CACHE_VERSION,
 		pricingFingerprint: pricingFingerprintValue,
 		pricingIdentityCutoffAll,
 		pricingIdentityCutoffs,
 		sessions: {}
 	};
+	const runtime = runtimeOf(cache);
+	// A pricing identity/catalog change invalidates all derived billing. Mark
+	// the replacement dirty even when the next collection deliberately avoids
+	// a persisted scan, so the stale fingerprint cannot survive a restart.
+	if (fingerprintChanged) runtime.dirty = true;
+	return cache;
 }
 
 function restoredCache(parsed, pricingFingerprintValue) {
@@ -332,7 +370,7 @@ function restoredCache(parsed, pricingFingerprintValue) {
 	for (const [id, entry] of Object.entries(parsed.sessions)) {
 		if (typeof id === "string" && id.length > 0) sessions[id] = parseSession(entry);
 	}
-	return {
+	const cache = {
 		version: CACHE_VERSION,
 		pricingFingerprint: pricingFingerprintValue,
 		pricingIdentityCutoffAll: Number.isFinite(parsed.pricingIdentityCutoffAll) && parsed.pricingIdentityCutoffAll >= 0
@@ -341,6 +379,8 @@ function restoredCache(parsed, pricingFingerprintValue) {
 		pricingIdentityCutoffs: parsePricingIdentityCutoffs(parsed.pricingIdentityCutoffs),
 		sessions
 	};
+	runtimeOf(cache);
+	return cache;
 }
 
 /** Load against the current runtime provider/pricing fingerprint. */
@@ -374,6 +414,8 @@ async function loadCache(pricingFingerprintValue) {
 
 /** Persist the cache atomically (temp + rename); failures are logged, never fatal. */
 async function saveCache(ctx, cache) {
+	const runtime = runtimeOf(cache);
+	if (!runtime.dirty) return false;
 	try {
 		const path = cachePath();
 		await mkdir(dirname(path), { recursive: true });
@@ -388,18 +430,32 @@ async function saveCache(ctx, cache) {
 		const tmp = `${path}.tmp`;
 		await writeFile(tmp, JSON.stringify(serialized), "utf8");
 		await rename(tmp, path);
+		runtime.dirty = false;
+		diagnostic(ctx, "cacheWrites");
+		return true;
 	} catch (error) {
 		ctx.logger.warn(`usage-stats: saving usage cache failed: ${String(error)}`);
+		return false;
 	}
 }
 
-/** Single-flight guard: concurrent requests share one aggregation run. */
-function withLock(run) {
-	if (inflight !== null) return inflight;
-	inflight = run().finally(() => {
-		inflight = null;
+/**
+ * Single-flight guard: concurrent requests share compatible aggregation work.
+ * A full persisted scan cannot be satisfied by an already-running live-only
+ * collection; it waits for that run and then performs its own full pass.
+ */
+function withCollectionLock(scanPersisted, run) {
+	if (inflight !== null) {
+		if (!scanPersisted || inflight.scanPersisted) return inflight.promise;
+		const waitForLive = () => withCollectionLock(true, run);
+		return inflight.promise.then(waitForLive, waitForLive);
+	}
+	const entry = { scanPersisted, promise: null };
+	entry.promise = run().finally(() => {
+		if (inflight === entry) inflight = null;
 	});
-	return inflight;
+	inflight = entry;
+	return entry.promise;
 }
 //#endregion
 
@@ -416,10 +472,47 @@ function withLock(run) {
  * to be contiguous with the last folded seq — a gap or an empty delta means
  * the log was truncated/rewritten, so the session is refolded from scratch.
  * Sessions that vanished are dropped, and a session switching between
- * live/persisted is refolded from scratch to stay exact.
+ * live/persisted is refolded from scratch to stay exact. High-frequency UI
+ * reads pass `{ scanPersisted: false }`: cached persisted folds remain in the
+ * aggregate, but the persistence backend is not enumerated or read. The
+ * five-minute background fold and exports use the default full scan.
  */
-export async function collectUsage(ctx, config = { monitors: {}, budgets: validateBudgetConfig() }) {
-	return withLock(async () => {
+function liveSessionAdapter(session) {
+	if (session === null || typeof session !== "object") throw new TypeError("live session must be an object");
+	if (typeof session.snapshotEvents === "function") {
+		if (!("seq" in session)) throw new TypeError("live session exposes an incomplete snapshot API");
+		return {
+			count() {
+				const count = session.seq;
+				if (!Number.isSafeInteger(count) || count < 0) throw new TypeError("live session seq must be a non-negative safe integer");
+				return count;
+			},
+			tail(fromSeq) {
+				const events = session.snapshotEvents(fromSeq);
+				if (!Array.isArray(events)) throw new TypeError("live session snapshotEvents() must return an array");
+				return events;
+			}
+		};
+	}
+	const legacyEvents = session.events;
+	if (!Array.isArray(legacyEvents)) throw new TypeError("live session does not expose a supported snapshot API");
+	return {
+		count() {
+			const events = session.events;
+			if (!Array.isArray(events)) throw new TypeError("legacy live session events must be an array");
+			return events.length;
+		},
+		tail(fromSeq) {
+			const events = session.events;
+			if (!Array.isArray(events)) throw new TypeError("legacy live session events must be an array");
+			return events.slice(fromSeq);
+		}
+	};
+}
+
+export async function collectUsage(ctx, config = { monitors: {}, budgets: validateBudgetConfig() }, options = {}) {
+	const scanPersisted = options?.scanPersisted !== false;
+	return withCollectionLock(scanPersisted, async () => {
 		const providers = await configuredProviders(ctx);
 		const runtimePricingFingerprint = pricingFingerprint({ providers, config });
 		const cache = await loadCache(runtimePricingFingerprint);
@@ -437,13 +530,23 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 		if (live !== void 0) {
 			for (const session of live.list()) {
 				attached.add(session.id);
-				const state = cache.sessions[session.id] ?? createUsageState();
-				if (typeof session.title === "string") state.title = session.title;
+				const liveAdapter = liveSessionAdapter(session);
+				let state = cache.sessions[session.id];
+				let stateChanged = false;
+				if (state === void 0) {
+					state = createUsageState();
+					stateChanged = true;
+				}
+				if (typeof session.title === "string" && state.title !== session.title) {
+					state.title = session.title;
+					stateChanged = true;
+				}
 				if (state.kind !== "live") {
 					// Live/persisted transition: refold the whole in-memory log.
 					resetUsageState(state);
+					stateChanged = true;
 				}
-				const count = session.events.length;
+				const count = liveAdapter.count();
 				if (count < (state.consumed ?? 0)) {
 					// The in-memory log shrank below the folded cursor — DSH
 					// restores sessions from disk as compressed summaries after
@@ -452,45 +555,69 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 					// forever (#23). The cursor is meaningless against the
 					// rebuilt log: refold it from scratch.
 					resetUsageState(state);
+					stateChanged = true;
 				}
 				if ((state.consumed ?? 0) < count) {
-					applyUsageDelta(state, session.events.slice(state.consumed ?? 0), { estimateCost });
+					applyUsageDelta(state, liveAdapter.tail(state.consumed ?? 0), { estimateCost });
 					state.consumed = count;
+					stateChanged = true;
+				}
+				if (state.kind !== "live") {
+					state.kind = "live";
+					stateChanged = true;
 				}
-				state.kind = "live";
 				cache.sessions[session.id] = state;
+				if (stateChanged) markCacheChanged(cache);
 			}
 		}
 		const persistence = ctx.get("sessionPersistence");
 		const persistedIds = new Set();
-		if (persistence !== void 0) {
+		if (scanPersisted && persistence !== void 0) {
 			// Prefer the backend's opaque per-log revisions (no file I/O in the
 			// plugin, works for any backend that exposes listSnapshots).
 			let snapshots = null;
 			if (typeof persistence.listSnapshots === "function") {
 				try {
+					diagnostic(ctx, "listSnapshots");
 					snapshots = await persistence.listSnapshots();
 				} catch (error) {
 					ctx.logger.warn(`usage-stats: listSnapshots failed, falling back to list(): ${String(error)}`);
 				}
 			}
-			const metas = snapshots !== null ? snapshots.map((entry) => entry.header) : await persistence.list();
+			let metas;
+			if (snapshots !== null) metas = snapshots.map((entry) => entry.header);
+			else {
+				diagnostic(ctx, "list");
+				metas = typeof persistence.list === "function" ? await persistence.list() : [];
+			}
 			const revisionOf = new Map();
 			if (snapshots !== null) for (const entry of snapshots) revisionOf.set(entry.header.id, entry.revision);
 			for (const meta of metas) {
 				persistedIds.add(meta.id);
 				if (attached.has(meta.id)) continue;
-				const state = cache.sessions[meta.id] ?? createUsageState();
-				if (typeof meta.title === "string") state.title = meta.title;
+				let state = cache.sessions[meta.id];
+				let stateChanged = false;
+				if (state === void 0) {
+					state = createUsageState();
+					stateChanged = true;
+				}
+				if (typeof meta.title === "string" && state.title !== meta.title) {
+					state.title = meta.title;
+					stateChanged = true;
+				}
 				const revision = revisionOf.get(meta.id);
-				const changed = state.kind !== "persisted" || (revision !== void 0 && revision !== state.revision) || revision === void 0;
+				const revisionChanged = revision !== void 0 && revision !== state.revision;
+				const changed = state.kind !== "persisted" || revisionChanged || revision === void 0;
+				if (revisionChanged) stateChanged = true;
 				if (changed) {
 					try {
 						const wasPersisted = state.kind === "persisted";
 						const fromSeq = wasPersisted ? state.consumed : 0;
+						diagnostic(ctx, "readFrom");
 						const { events } = await persistence.readFrom(meta.id, fromSeq);
 						if (!wasPersisted) {
 							resetUsageState(state);
+							stateChanged = true;
 						}
 						const fresh = wasPersisted ? events.filter((event) => event.seq > (state.consumed ?? 0)) : events;
 						// readFrom is inclusive: an unchanged log returns exactly the
@@ -504,31 +631,51 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 						if (!contiguous && state.consumed > 0) {
 							// Log truncated or rewritten: refold the whole log.
 							resetUsageState(state);
+							stateChanged = true;
+							diagnostic(ctx, "readFrom");
 							const { events: allEvents } = await persistence.readFrom(meta.id, 0);
 							applyUsageDelta(state, allEvents, { estimateCost });
 							state.consumed = allEvents.length > 0 ? allEvents[allEvents.length - 1].seq : 0;
 						} else if (fresh.length > 0) {
 							applyUsageDelta(state, fresh, { estimateCost });
 							state.consumed = fresh[fresh.length - 1].seq;
+							stateChanged = true;
+						}
+						if (state.kind !== "persisted") {
+							state.kind = "persisted";
+							stateChanged = true;
+						}
+						if (revision !== void 0 && state.revision !== revision) {
+							state.revision = revision;
+							stateChanged = true;
 						}
-						state.kind = "persisted";
-						if (revision !== void 0) state.revision = revision;
 					} catch (error) {
 						ctx.logger.warn(`usage-stats: reading persisted session "${meta.id}" failed: ${String(error)}`);
 					}
 				}
 				cache.sessions[meta.id] = state;
+				if (stateChanged) markCacheChanged(cache);
+			}
+			for (const id of Object.keys(cache.sessions)) {
+				if (!attached.has(id) && !persistedIds.has(id)) {
+					delete cache.sessions[id];
+					markCacheChanged(cache);
+				}
 			}
 		}
-		for (const id of Object.keys(cache.sessions)) {
-			if (!attached.has(id) && !persistedIds.has(id)) delete cache.sessions[id];
-		}
-		const byDay = new Map();
-		const billingByDay = new Map();
-		for (const state of Object.values(cache.sessions)) {
-			mergeInto(byDay, state.days);
-			mergeBillingInto(billingByDay, state.billing.days);
+		const runtime = runtimeOf(cache);
+		if (runtime.aggregate === null || runtime.aggregateDirty) {
+			diagnostic(ctx, "aggregateRebuilds");
+			const byDay = new Map();
+			const billingByDay = new Map();
+			for (const state of Object.values(cache.sessions)) {
+				mergeInto(byDay, state.days);
+				mergeBillingInto(billingByDay, state.billing.days);
+			}
+			runtime.aggregate = { byDay, billingByDay };
+			runtime.aggregateDirty = false;
 		}
+		const { byDay, billingByDay } = runtime.aggregate;
 		// Keep the atomic cache write inside the single-flight section. Otherwise
 		// overlapping saves can race on the same temporary file.
 		await saveCache(ctx, cache);
@@ -545,7 +692,7 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 async function handleUsage(ctx, config, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		const result = await collectUsage(ctx, config);
+		const result = await collectUsage(ctx, config, { scanPersisted: false });
 		json(res, 200, { ok: true, ...result });
 	} catch (error) {
 		ctx.logger.warn(`usage-stats: usage aggregation failed: ${String(error)}`);
@@ -562,7 +709,7 @@ function exportFailure(ctx, kind, error, res) {
 async function handleDailyExport(ctx, config, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		attachment(res, "text/csv; charset=utf-8", "dsh-usage-daily.csv", dailyCsv(await collectUsage(ctx, config)));
+		attachment(res, "text/csv; charset=utf-8", "dsh-usage-daily.csv", dailyCsv(await collectUsage(ctx, config, { scanPersisted: true })));
 	} catch (error) {
 		exportFailure(ctx, "daily CSV", error, res);
 	}
@@ -571,7 +718,7 @@ async function handleDailyExport(ctx, config, req, res) {
 async function handleSessionsExport(ctx, config, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		attachment(res, "text/csv; charset=utf-8", "dsh-usage-sessions.csv", sessionsCsv(await collectUsage(ctx, config)));
+		attachment(res, "text/csv; charset=utf-8", "dsh-usage-sessions.csv", sessionsCsv(await collectUsage(ctx, config, { scanPersisted: true })));
 	} catch (error) {
 		exportFailure(ctx, "session CSV", error, res);
 	}
@@ -580,7 +727,10 @@ async function handleSessionsExport(ctx, config, req, res) {
 async function handleJsonExport(ctx, config, accounts, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		const [usage, providerViews] = await Promise.all([collectUsage(ctx, config), accounts.providerViews()]);
+		const [usage, providerViews] = await Promise.all([
+			collectUsage(ctx, config, { scanPersisted: true }),
+			accounts.providerViews()
+		]);
 		attachment(res, "application/json; charset=utf-8", "dsh-usage-stats.json", JSON.stringify(jsonExport(usage, providerViews)));
 	} catch (error) {
 		exportFailure(ctx, "JSON", error, res);
@@ -635,7 +785,7 @@ async function configuredProviders(ctx) {
  * events), and add no stream listener, provider request, cache, or usage ledger.
  */
 export async function collectSessionContext(ctx, sessionId, config = { monitors: {} }, selectedRoute = null) {
-	await collectUsage(ctx, config);
+	await collectUsage(ctx, config, { scanPersisted: false });
 	const sessions = ctx.get("sessions");
 	const live = sessions?.get?.(sessionId) ?? sessions?.list?.().find((session) => session.id === sessionId);
 	if (live === void 0) return null;
@@ -655,8 +805,8 @@ export async function collectSessionContext(ctx, sessionId, config = { monitors:
 }
 
 /** Resolve the current account ids for every live session without a new ledger or provider guess. */
-export async function collectActiveAccountIds(ctx, config = { monitors: {} }) {
-	await collectUsage(ctx, config);
+export async function collectActiveAccountIds(ctx, config = { monitors: {} }, options = { scanPersisted: false }) {
+	await collectUsage(ctx, config, options);
 	const sessions = ctx.get("sessions")?.list?.() ?? [];
 	const cache = loadedCache;
 	if (cache === null) return [];
@@ -917,8 +1067,8 @@ export function startBackgroundRefresh(ctx, accounts, deps = {}) {
 			const at = now();
 			if (force || at >= nextUsageAt) {
 				try {
-					if (accountRefreshEnabled) accounts.setActiveProviders(await collectActiveAccountIds(ctx, config));
-					else await collectUsage(ctx, config);
+					if (accountRefreshEnabled) accounts.setActiveProviders(await collectActiveAccountIds(ctx, config, { scanPersisted: true }));
+					else await collectUsage(ctx, config, { scanPersisted: true });
 				} catch (error) {
 					ctx.logger.warn(`usage-stats: background usage refresh failed: ${String(error)}`);
 				}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ychris12138/dsh-usage-stats",
   "description": "Token usage, provider accounts, session cost estimates, budgets, and exports for the dsh web GUI",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ychris12138/dsh-usage-stats.git"
@@ -24,6 +24,7 @@
     "docs/release-checklist.md",
     "docs/release-notes-v0.3.0.md",
     "docs/release-notes-v0.3.1.md",
+    "docs/release-notes-v0.3.2.md",
     "scripts/install.mjs",
     "README.md",
     "LICENSE",