dsh-skill-hub 0.3.9 → 0.3.10

package/lib/index.js

@@ -264,6 +264,30 @@ function hydrateMigratedState(migrated) {
 			});
 		}
 	}
+	/**
+	* Validate the cold-path revision bucket: corrupt entries degrade to a
+	* re-read (the revision simply misses), never to bad counts.
+	*/
+	function cleanColdRevisions(raw) {
+		if (raw === null || typeof raw !== "object") return {};
+		const revisions = {};
+		for (const [id, entry] of Object.entries(raw)) {
+			if (entry === null || typeof entry !== "object") continue;
+			const { rev, createdAt, counts } = entry;
+			if (typeof rev !== "string" || typeof createdAt !== "number" || counts === null || typeof counts !== "object") continue;
+			const clean = {};
+			for (const [name, stat] of Object.entries(counts)) if (stat !== null && typeof stat === "object" && typeof stat.count === "number" && typeof stat.lastUsed === "number") clean[name] = {
+				count: stat.count,
+				lastUsed: stat.lastUsed
+			};
+			revisions[id] = {
+				rev,
+				createdAt,
+				counts: clean
+			};
+		}
+		return { coldRevisions: revisions };
+	}
 	let skillStats = void 0;
 	const savedStats = migrated.skillStats;
 	if (savedStats !== null && typeof savedStats === "object" && typeof savedStats.frozenBefore === "number" && typeof savedStats.lastFullReconcile === "number" && typeof savedStats.windowDays === "number" && typeof savedStats.frozenSessions === "object" && savedStats.frozenSessions !== null) {
@@ -291,7 +315,8 @@ function hydrateMigratedState(migrated) {
 			frozenBefore: savedStats.frozenBefore,
 			frozenSessions: sessions,
 			lastFullReconcile: savedStats.lastFullReconcile,
-			...lastTotals !== void 0 ? { lastTotals } : {}
+			...lastTotals !== void 0 ? { lastTotals } : {},
+			...cleanColdRevisions(savedStats.coldRevisions)
 		};
 	}
 	let marketStats = void 0;
@@ -757,7 +782,8 @@ var SkillHubStore = class {
 		return this.skillStats !== void 0 ? {
 			...this.skillStats,
 			frozenSessions: { ...this.skillStats.frozenSessions },
-			...this.skillStats.lastTotals !== void 0 ? { lastTotals: [...this.skillStats.lastTotals] } : {}
+			...this.skillStats.lastTotals !== void 0 ? { lastTotals: [...this.skillStats.lastTotals] } : {},
+			...this.skillStats.coldRevisions !== void 0 ? { coldRevisions: { ...this.skillStats.coldRevisions } } : {}
 		} : void 0;
 	}
 	/** Persist a usage-statistics checkpoint (after every completed scan; cadence follows the scan TTL). */
@@ -768,7 +794,8 @@ var SkillHubStore = class {
 			frozenBefore: state.frozenBefore,
 			frozenSessions: { ...state.frozenSessions },
 			lastFullReconcile: state.lastFullReconcile,
-			...state.lastTotals !== void 0 ? { lastTotals: [...state.lastTotals] } : {}
+			...state.lastTotals !== void 0 ? { lastTotals: [...state.lastTotals] } : {},
+			...state.coldRevisions !== void 0 ? { coldRevisions: { ...state.coldRevisions } } : {}
 		};
 		await this.persist();
 	}
@@ -2783,10 +2810,21 @@ function catalogRoutes(deps) {
 					});
 					return;
 				}
+				const display = configOf(deps);
+				if (display.showUseCount === false && display.showUseTime === false && display.showGroupSummary === false) {
+					writeJson(res, 200, {
+						ok: true,
+						available: false,
+						stats: []
+					});
+					return;
+				}
+				const stats = await deps.stats();
 				writeJson(res, 200, {
 					ok: true,
 					available: true,
-					stats: await deps.stats()
+					...deps.stats.source !== void 0 ? { source: deps.stats.source } : {},
+					stats
 				});
 			}
 		}
@@ -3981,6 +4019,55 @@ function makeRoutes(deps) {
 /** Fallback freeze horizon when no rolling window is configured (14 days). */
 const STATS_FREEZE_AFTER_MS = 336 * 60 * 60 * 1e3;
 const DAY_MS = 1440 * 60 * 1e3;
+/**
+* Adapt a host persistence service to {@link SessionPersistenceLike}.
+* Shape-checked only (no I/O): returns undefined when the value is not a
+* usable seam, so callers fall back to the query path. The adapter re-resolves
+* nothing and holds no state — a replaced host service surfaces as ordinary
+* per-call failures, which scans already tolerate.
+*/
+function asPersistenceSeam(service) {
+	if (service === null || typeof service !== "object") return void 0;
+	const { list, open } = service;
+	if (typeof list !== "function" || typeof open !== "function") return void 0;
+	const listFn = list.bind(service);
+	const openFn = open.bind(service);
+	return {
+		list: async () => {
+			const rows = await listFn();
+			if (!Array.isArray(rows)) throw new Error("persistence list shape mismatch");
+			return rows.map((row) => {
+				const record = row;
+				const id = record.header?.id;
+				if (typeof id !== "string" && typeof id !== "number") throw new Error("persistence snapshot shape mismatch");
+				const created = record.header?.createdAt;
+				return {
+					header: {
+						id,
+						...typeof created === "number" ? { createdAt: created } : {}
+					},
+					revision: String(record.revision)
+				};
+			});
+		},
+		open: async (id, access) => {
+			const raw = await openFn(id, access);
+			if (raw === null || typeof raw !== "object") throw new Error("persistence handle shape mismatch");
+			const { read, close } = raw;
+			if (typeof read !== "function" || typeof close !== "function") throw new Error("persistence handle shape mismatch");
+			const readFn = read.bind(raw);
+			const closeFn = close.bind(raw);
+			return {
+				read: async () => {
+					const events = (await readFn(0, void 0))?.events;
+					if (!Array.isArray(events)) throw new Error("persistence read shape mismatch");
+					return { events };
+				},
+				close: () => closeFn()
+			};
+		}
+	};
+}
 /** Collect per-skill invocation counts and last-used times from one session. */
 function countSkillInvocations(events) {
 	const stats = /* @__PURE__ */ new Map();
@@ -4029,8 +4116,11 @@ async function mapConcurrent(items, limit, worker) {
 	await Promise.all(runners);
 	return results;
 }
-/** Max parallel session-log reads per scan (read-only; merge is order-independent). */
-const SCAN_READ_CONCURRENCY = 6;
+/** Max parallel session-log reads per scan. Reads on the query path restore +
+* replay-validate a full Session each (structuredClone × 2 + deepFreeze), so
+* this stays 1: at most one restored log is resident and a heavy corpus costs
+* wall time, never a memory spike. The cold path reads sequentially anyway. */
+const SCAN_READ_CONCURRENCY = 1;
 function mergeInto(totals, counted) {
 	for (const [name, stat] of counted) {
 		const total = totals[name];
@@ -4087,8 +4177,9 @@ async function scan(query, checkpoint, nowMs, windowDays) {
 			const counted = countedList[index];
 			if (counted === void 0) return;
 			const created = record.header.createdAt;
-			if (isFrozen(record, cutoff) && counted.size > 0 && typeof created === "number") cache[record.header.id] = {
-				createdAt: created,
+			const id = record.header.id;
+			if (counted.size > 0 && (isFrozen(record, cutoff) || !(typeof created === "number" && created > 0))) cache[id] = {
+				createdAt: typeof created === "number" ? created : 0,
 				counts: Object.fromEntries(counted)
 			};
 			if (inWindow(created, windowDays, nowMs)) mergeInto(totals, counted);
@@ -4103,7 +4194,8 @@ async function scan(query, checkpoint, nowMs, windowDays) {
 		};
 	}
 	const recent = {};
-	const recentList = await mapConcurrent(sessions.filter((record) => !isFrozen(record, checkpoint.frozenBefore)), SCAN_READ_CONCURRENCY, async (record) => {
+	const frozenIds = checkpoint.frozenSessions;
+	const recentList = await mapConcurrent(sessions.filter((record) => !Object.prototype.hasOwnProperty.call(frozenIds, record.header.id) && !isFrozen(record, checkpoint.frozenBefore)), SCAN_READ_CONCURRENCY, async (record) => {
 		try {
 			return countSkillInvocations((await query.readSession(record.header.id)).events);
 		} catch {
@@ -4116,7 +4208,7 @@ async function scan(query, checkpoint, nowMs, windowDays) {
 	}
 	const totals = {};
 	for (const [id, entry] of Object.entries(checkpoint.frozenSessions)) {
-		if (!inWindow(entry.createdAt, windowDays, nowMs)) {
+		if (entry.createdAt > 0 && !inWindow(entry.createdAt, windowDays, nowMs)) {
 			delete checkpoint.frozenSessions[id];
 			continue;
 		}
@@ -4129,6 +4221,69 @@ async function scan(query, checkpoint, nowMs, windowDays) {
 	};
 }
 /**
+* One pass over the corpus through the persistence seam. Reads are strictly
+* sequential and each handle is closed before the next opens, so at most one
+* raw log is resident. A session is re-read only when its revision token
+* changed since the checkpoint; the rolling window is applied from the
+* listing headers, so out-of-window logs are never even opened. Live sessions
+* (in-memory, possibly newer than their persisted revision) are read through
+* `readLive` and never enter the revision cache.
+*
+* A `list()` failure rejects — the reader keeps the previous totals, and the
+* next poll retries. Per-session failures are skipped, never fatal.
+*/
+async function scanCold(persistence, checkpoint, nowMs, windowDays, liveIds = /* @__PURE__ */ new Set(), readLive = async () => void 0) {
+	const revisions = checkpoint.coldRevisions ?? (checkpoint.coldRevisions = {});
+	const totals = {};
+	const snapshots = await persistence.list();
+	const seen = /* @__PURE__ */ new Set();
+	for (const snapshot of snapshots) {
+		const id = snapshot.header.id;
+		seen.add(id);
+		if (liveIds.has(id)) continue;
+		const created = snapshot.header.createdAt;
+		if (!inWindow(created, windowDays, nowMs)) {
+			delete revisions[id];
+			continue;
+		}
+		const rev = snapshot.revision;
+		const cached = revisions[id];
+		if (cached !== void 0 && cached.rev === rev) {
+			mergeInto(totals, new Map(Object.entries(cached.counts)));
+			continue;
+		}
+		let counted;
+		try {
+			const handle = await persistence.open(snapshot.header.id, "read");
+			try {
+				counted = countSkillInvocations((await handle.read()).events);
+			} finally {
+				await handle.close();
+			}
+		} catch {
+			continue;
+		}
+		revisions[id] = {
+			rev,
+			createdAt: typeof created === "number" ? created : 0,
+			counts: Object.fromEntries(counted)
+		};
+		mergeInto(totals, counted);
+	}
+	for (const id of Object.keys(revisions)) if (!seen.has(id)) delete revisions[id];
+	for (const id of liveIds) {
+		let events;
+		try {
+			events = await readLive(id);
+		} catch {
+			continue;
+		}
+		if (events === void 0) continue;
+		mergeInto(totals, countSkillInvocations(events));
+	}
+	return toSorted(totals);
+}
+/**
 * Wrap a query in a stale-while-revalidate cache: responses never wait for a
 * full session-log scan. While the TTL is fresh the cached totals are
 * returned; after expiry the stale totals are returned immediately and a
@@ -4154,21 +4309,30 @@ function createSkillStatsReader(query, ttlMs = 3e5, options = {}) {
 	let cachedAt = 0;
 	let refreshing = null;
 	let lastScanDurationMs = 0;
-	return async () => {
+	const reader = async () => {
 		const startedAt = now();
 		const base = typeof ttlMs === "function" ? ttlMs() : ttlMs;
 		const ttl = Math.max(base, lastScanDurationMs * 3);
 		if (cached !== void 0 && startedAt - cachedAt < ttl) return cached;
 		if (refreshing === null) {
 			const windowDays = options.windowDays?.() ?? 0;
-			refreshing = scan(query, checkpoint, startedAt, windowDays).then(({ stats }) => {
+			refreshing = (options.persistence !== void 0 ? (async () => {
+				let liveIds = /* @__PURE__ */ new Set();
+				if (options.listLiveIds !== void 0) try {
+					liveIds = new Set((await options.listLiveIds()).map((id) => String(id)));
+				} catch {}
+				return scanCold(options.persistence, checkpoint, startedAt, windowDays, liveIds, async (id) => {
+					return (await options.readLiveSession?.(id))?.events;
+				});
+			})() : scan(query, checkpoint, startedAt, windowDays).then(({ stats }) => stats)).then((stats) => {
 				cached = stats;
 				cachedAt = now();
 				lastScanDurationMs = Math.max(0, cachedAt - startedAt);
 				checkpoint.lastTotals = stats;
 				options.onCheckpoint?.({
 					...checkpoint,
-					frozenSessions: { ...checkpoint.frozenSessions }
+					frozenSessions: { ...checkpoint.frozenSessions },
+					...checkpoint.coldRevisions !== void 0 ? { coldRevisions: { ...checkpoint.coldRevisions } } : {}
 				});
 			}).catch(() => {}).finally(() => {
 				refreshing = null;
@@ -4176,6 +4340,8 @@ function createSkillStatsReader(query, ttlMs = 3e5, options = {}) {
 		}
 		return cached ?? [];
 	};
+	reader.source = options.persistence !== void 0 ? "cold" : "query";
+	return reader;
 }
 //#endregion
 //#region src/index.ts
@@ -4313,9 +4479,17 @@ function apply(ctx, config) {
 			ctx.logger.warn("[dsh-skill-hub] sidecar config migration into the settings namespace failed", error);
 		}
 	})();
-	ctx.inject(["sessionQuery"], (sctx) => {
+	let statsQuery;
+	let statsPersistence;
+	let statsGeneration = 0;
+	const wireStats = () => {
+		const query = statsQuery;
+		if (query === void 0) return;
+		const generation = ++statsGeneration;
+		const cold = statsPersistence;
 		(async () => {
 			const saved = await store.getSkillStatsState().catch(() => void 0);
+			if (generation !== statsGeneration) return;
 			const scanMinutes = () => {
 				const value = current().statsScanMinutes;
 				return typeof value === "number" && value >= 1 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsScanMinutes;
@@ -4324,19 +4498,59 @@ function apply(ctx, config) {
 				const value = current().statsWindowDays;
 				return typeof value === "number" && value >= 0 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsWindowDays;
 			};
-			const reader = createSkillStatsReader(sctx.sessionQuery, () => scanMinutes() * 6e4, {
+			const reader = createSkillStatsReader(query, () => scanMinutes() * 6e4, {
 				checkpoint: saved,
 				windowDays,
+				...cold === void 0 ? {} : {
+					persistence: cold,
+					listLiveIds: async () => {
+						try {
+							return (await query.listSessions()).filter((record) => record.live === true).map((record) => record.header.id);
+						} catch {
+							return [];
+						}
+					},
+					readLiveSession: async (id) => {
+						try {
+							return { events: (await query.readSession(id)).events };
+						} catch {
+							return;
+						}
+					}
+				},
 				onCheckpoint: (next) => {
 					store.saveSkillStatsState(next).catch((error) => {
 						ctx.logger.warn("[dsh-skill-hub] persisting skill-stats checkpoint failed", error);
 					});
 				}
 			});
+			if (generation !== statsGeneration) return;
+			ctx.logger.info(`[dsh-skill-hub] stats seam: ${cold === void 0 ? "session-query (fallback)" : "session-persistence (cold)"}`);
 			stats = reader;
 			sync();
-			reader();
 		})();
+	};
+	ctx.inject(["sessionQuery"], (sctx) => {
+		statsQuery = sctx.sessionQuery;
+		wireStats();
+		sctx.inject(["sessionPersistence"], (pctx) => {
+			(async () => {
+				const raw = pctx.sessionPersistence;
+				const seam = asPersistenceSeam(raw);
+				if (seam === void 0) {
+					ctx.logger.warn("[dsh-skill-hub] sessionPersistence shape mismatch, staying on query fallback");
+					return;
+				}
+				try {
+					await seam.list();
+				} catch (error) {
+					ctx.logger.warn("[dsh-skill-hub] persistence seam probe failed, staying on query fallback", error);
+					return;
+				}
+				statsPersistence = seam;
+				wireStats();
+			})();
+		});
 	});
 }
 //#endregion

package/lib/types/protocol/stats.d.ts

@@ -14,14 +14,24 @@ export interface StatsResponse {
     available: boolean;
     /** Sorted per-skill invocation counts. */
     stats: SkillStat[];
+    /** Which read path produced the counts (debug aid for memory-issue follow-ups). */
+    source?: 'cold' | 'query';
 }
 /**
  * Persisted incremental-scan checkpoint for the usage statistics (sidecar
- * `skillStats` field). Sessions created before `frozenBefore` are treated as
- * finalized: their per-session counts live in `frozenSessions` (only sessions
- * with at least one invocation are kept) and they are not re-read on
- * incremental scans. A daily full reconciliation rebuilds the cache and
- * advances the watermark, so a resumed old session is eventually re-counted.
+ * `skillStats` field). Two buckets cover the two read paths:
+ *
+ * - `coldRevisions` (preferred): per-session counts keyed by the persistence
+ *   seam's opaque revision token. A session is re-read only when its revision
+ *   changes, so resumed old sessions are picked up exactly and the daily full
+ *   reconciliation is unnecessary on this path.
+ * - `frozenSessions` + `frozenBefore` + `lastFullReconcile` (fallback): the
+ *   legacy time-watermark scheme used when only the heavier `sessionQuery`
+ *   seam is available. Sessions older than the effective watermark are treated
+ *   as finalized: their per-session counts live in `frozenSessions` (only
+ *   sessions with at least one invocation are kept) and they are not re-read
+ *   on incremental scans. A daily full reconciliation rebuilds the cache and
+ *   advances the watermark, so a resumed old session is eventually re-counted.
  */
 export interface SkillStatsCheckpoint {
     /** The rolling-window configuration this checkpoint was built for (0 = all history). */
@@ -43,4 +53,22 @@ export interface SkillStatsCheckpoint {
      * start so a restart still shows numbers while the background rescan runs.
      */
     lastTotals?: SkillStat[];
+    /**
+     * Per-session counts read through the persistence seam, keyed by session id
+     * and stamped with the revision they were read at. Absent until the first
+     * cold-path scan completes; the query fallback path ignores it.
+     */
+    coldRevisions?: Record<string, ColdRevisionEntry>;
+}
+/** One cold-path cache entry: what a session's log contained at a revision. */
+export interface ColdRevisionEntry {
+    /** The persistence seam's opaque revision token, stringified. */
+    rev: string;
+    /** header.createdAt at read time (0 when the header carried none). */
+    createdAt: number;
+    /** Per-skill counts (empty when the session invoked no skill). */
+    counts: Record<string, {
+        count: number;
+        lastUsed: number;
+    }>;
 }

package/lib/types/stats.d.ts

@@ -13,16 +13,27 @@
  * Counting is per-skill-name, not per-source: a name may resolve to different
  * files across projects, but the model-facing identity is the kebab-case name.
  *
- * Scaling (per-session checkpoint + incremental scans): a full scan
- * decompresses every session log, which grows linearly with total history.
- * Sessions older than the effective watermark are therefore treated as
- * finalized — their per-session counts live in the checkpoint (persisted by
- * the host via the sidecar) and are skipped on incremental scans; only the
- * recent window is re-read. A daily full reconciliation rebuilds the cache
- * and advances the watermark, so a resumed old session is eventually
- * re-counted. On top of that, the reader's TTL adapts to the measured scan
- * duration (STATS_TTL_SCAN_FACTOR), so a heavy scan also lowers its own
- * frequency.
+ * Two read paths, cheapest first:
+ *
+ * 1. Cold path (preferred): the host's `sessionPersistence` seam serves raw
+ *    stored logs — decompress + parse only, no Session restore, no
+ *    structuredClone-per-event, no deepFreeze. `list()` also reports an opaque
+ *    per-session revision token, so the checkpoint re-reads exactly the
+ *    sessions whose revision changed (plus live sessions via the query seam).
+ *    No time watermark, no daily full reconciliation.
+ * 2. Query fallback: `sessionQuery.readSession` restores + replay-validates a
+ *    full Session per call (structuredClone × 2 + deepFreeze). Reads are
+ *    strictly sequential (concurrency 1) so at most one restored log is
+ *    resident, and a per-session checkpoint + incremental scans keeps the
+ *    repeat cost to the recent window: a full scan decompresses every session
+ *    log, which grows linearly with total history. Sessions older than the
+ *    effective watermark are therefore treated as finalized — their
+ *    per-session counts live in the checkpoint (persisted by the host via the
+ *    sidecar) and are skipped on incremental scans; only the recent window is
+ *    re-read. A daily full reconciliation rebuilds the cache and advances the
+ *    watermark, so a resumed old session is eventually re-counted. On top of
+ *    that, the reader's TTL adapts to the measured scan duration
+ *    (STATS_TTL_SCAN_FACTOR), so a heavy scan also lowers its own frequency.
  *
  * Rolling window (statsWindowDays > 0): totals only include sessions created
  * within the last N days. The watermark then equals the window edge, so
@@ -52,6 +63,41 @@ export interface SessionQueryLike {
         events: SessionEvent[];
     }>;
 }
+/**
+ * Narrow structural view of the host's session-persistence seam (kept loose
+ * so no runtime import of host packages is needed — the owner adapts the real
+ * service via {@link asPersistenceSeam}). Raw log reads here cost decompress +
+ * parse only: no Session restore, no per-event clone, no deep-freeze.
+ */
+export interface ColdSessionSnapshot {
+    header: {
+        id: SessionId;
+        createdAt?: number;
+    };
+    /** Opaque per-session change token, kept as its string form. */
+    revision: string;
+}
+/** One read handle over a stored session log (always closed after counting). */
+export interface ColdSessionHandle {
+    read(): Promise<{
+        events: SessionEvent[];
+    }>;
+    close(): Promise<void> | void;
+}
+/** Minimal persistence surface the cold scan needs. */
+export interface SessionPersistenceLike {
+    /** Lightweight listing: headers + revision tokens, no event logs. */
+    list(): Promise<readonly ColdSessionSnapshot[]>;
+    open(id: SessionId, access: 'read'): Promise<ColdSessionHandle>;
+}
+/**
+ * Adapt a host persistence service to {@link SessionPersistenceLike}.
+ * Shape-checked only (no I/O): returns undefined when the value is not a
+ * usable seam, so callers fall back to the query path. The adapter re-resolves
+ * nothing and holds no state — a replaced host service surfaces as ordinary
+ * per-call failures, which scans already tolerate.
+ */
+export declare function asPersistenceSeam(service: unknown): SessionPersistenceLike | undefined;
 /** Per-skill invocation stats in one session's event log. */
 export interface InvocationStat {
     count: number;
@@ -60,13 +106,34 @@ export interface InvocationStat {
 }
 /** Collect per-skill invocation counts and last-used times from one session. */
 export declare function countSkillInvocations(events: readonly SessionEvent[]): Map<string, InvocationStat>;
+/**
+ * One pass over the corpus through the persistence seam. Reads are strictly
+ * sequential and each handle is closed before the next opens, so at most one
+ * raw log is resident. A session is re-read only when its revision token
+ * changed since the checkpoint; the rolling window is applied from the
+ * listing headers, so out-of-window logs are never even opened. Live sessions
+ * (in-memory, possibly newer than their persisted revision) are read through
+ * `readLive` and never enter the revision cache.
+ *
+ * A `list()` failure rejects — the reader keeps the previous totals, and the
+ * next poll retries. Per-session failures are skipped, never fatal.
+ */
+export declare function scanCold(persistence: SessionPersistenceLike, checkpoint: SkillStatsCheckpoint, nowMs: number, windowDays: number, liveIds?: ReadonlySet<string>, readLive?: (id: SessionId) => Promise<readonly SessionEvent[] | undefined>): Promise<SkillStat[]>;
 /**
  * Full-corpus totals in one shot (no checkpoint reuse). Kept as the
  * reference implementation for tests and one-off callers.
  */
 export declare function readSkillStats(query: SessionQueryLike, windowDays?: number): Promise<SkillStat[]>;
+/**
+ * Full-corpus totals in one shot through the persistence seam (no checkpoint
+ * reuse). Reference implementation for tests and one-off callers.
+ */
+export declare function readColdSkillStats(persistence: SessionPersistenceLike, windowDays?: number): Promise<SkillStat[]>;
 /** A memoized stats reader (the panel polls, but logs change slowly). */
-export type SkillStatsReader = () => Promise<SkillStat[]>;
+export type SkillStatsReader = (() => Promise<SkillStat[]>) & {
+    /** Which read path this reader scans with (set at wiring; absent on test doubles). */
+    source?: 'cold' | 'query';
+};
 /** Optional wiring for {@link createSkillStatsReader}. */
 export interface SkillStatsReaderOptions {
     /** Checkpoint restored from the sidecar; absent means "start from zero". */
@@ -81,6 +148,14 @@ export interface SkillStatsReaderOptions {
      *  persist the checkpoint including the fresh totals. Cadence follows the
      *  scan TTL (minutes, not days) — the payload is tiny and writes are atomic. */
     onCheckpoint?: (checkpoint: SkillStatsCheckpoint) => void;
+    /** Preferred cheap seam: raw stored-log reads keyed by revision token. */
+    persistence?: SessionPersistenceLike;
+    /** Live session ids (usually 0-2) read through the query seam, not the cache. */
+    listLiveIds?: () => Promise<readonly SessionId[]>;
+    /** Full current log of one live session; undefined skips it for this scan. */
+    readLiveSession?: (id: SessionId) => Promise<{
+        events: SessionEvent[];
+    } | undefined>;
 }
 /**
  * Wrap a query in a stale-while-revalidate cache: responses never wait for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-hub",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "In-GUI skill hub for DeepSeek Harness (dsh): browse the full local skill catalog from the official ctx.skills registry (every root + third-party providers), toggle skills on/off, inspect bodies, surface frontmatter diagnostics, and scaffold new skills — plus a codex-style skill market (built-in catalog, upstream update checks, one-click update-all) with tracked source sync. The full manager beyond the read-only dsh-skill-manager browser.",
   "type": "module",
   "engines": {