sidekick-shared 0.28.3 → 0.29.1

package/dist/esm/parsers/codexRolloutOrigin.js

@@ -0,0 +1,107 @@
+/**
+ * Where a Codex rollout came from, read from its `session_meta` record:
+ * a session a person started, a fork of another session, or a subagent.
+ *
+ * Codex writes `session_meta.source` as a plain string for sessions started
+ * from a surface (`cli`, `vscode`, `exec`, …) and as an object for subagents:
+ * `{ subagent: { thread_spawn: { parent_thread_id, … } } }` for a spawned
+ * agent, `{ subagent: { other: 'guardian' } }` for internal reviewers, or
+ * `{ subagent: 'review' }`. The same JSON appears as a string in the state
+ * database's `threads.source`. A forked rollout records `forked_from_id`, and
+ * embeds its parent's `session_meta` after its own, so only the first counts.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module parsers/codexRolloutOrigin
+ */
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** A `source` value as an object: rollouts store it parsed, the database as JSON text. */
+function sourceObject(source) {
+    if (typeof source !== 'string')
+        return record(source);
+    if (!source.startsWith('{'))
+        return undefined;
+    try {
+        return record(JSON.parse(source));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parent thread id of a spawned subagent's `source` (object, or JSON text as
+ * stored in `threads.source`): `subagent.thread_spawn.parent_thread_id`.
+ */
+export function codexSpawnParentFromSource(source) {
+    const spawn = record(record(sourceObject(source)?.subagent)?.thread_spawn);
+    const parent = spawn?.parent_thread_id;
+    return typeof parent === 'string' ? parent : undefined;
+}
+function subagentKindOf(subagent) {
+    if (typeof subagent === 'string')
+        return nonEmpty(subagent);
+    const variant = record(subagent);
+    if (!variant)
+        return undefined;
+    const other = nonEmpty(variant.other);
+    if (other)
+        return other;
+    return Object.keys(variant)[0];
+}
+/** The `session_meta` payload of a record, of a bare payload, or of the first in a list. */
+function metaPayload(input) {
+    if (Array.isArray(input)) {
+        for (const item of input) {
+            const row = record(item);
+            if (row?.type === 'session_meta')
+                return record(row.payload);
+        }
+        return undefined;
+    }
+    const row = record(input);
+    if (!row)
+        return undefined;
+    if (row.type === 'session_meta')
+        return record(row.payload);
+    // A payload on its own, as `readSessionMeta()` returns it.
+    if (row.type === undefined && row.payload === undefined)
+        return row;
+    return undefined;
+}
+/**
+ * Origin of a Codex rollout from its `session_meta`. Accepts the parsed
+ * `session_meta` record, its payload, or the rollout's records in order (the
+ * first `session_meta` wins: a fork embeds its parent's after its own).
+ * Anything else yields `{ isSubagent: false }`.
+ */
+export function codexRolloutOrigin(input) {
+    const payload = metaPayload(input);
+    if (!payload)
+        return { isSubagent: false };
+    const forkedFromId = nonEmpty(payload.forked_from_id);
+    const object = sourceObject(payload.source);
+    const isSubagent = object !== undefined && 'subagent' in object;
+    const source = typeof payload.source === 'string' && object === undefined
+        ? nonEmpty(payload.source)
+        : isSubagent
+            ? 'subagent'
+            : undefined;
+    const parentId = forkedFromId ??
+        nonEmpty(codexSpawnParentFromSource(object)) ??
+        (isSubagent ? nonEmpty(payload.parent_thread_id) : undefined);
+    const subagentKind = isSubagent ? subagentKindOf(object?.subagent) : undefined;
+    return {
+        ...(forkedFromId ? { forkedFromId } : {}),
+        ...(source ? { source } : {}),
+        isSubagent,
+        ...(parentId ? { parentId } : {}),
+        ...(subagentKind ? { subagentKind } : {}),
+    };
+}

package/dist/esm/parsers/openCodeParser.js

@@ -11,6 +11,7 @@
  * @module parsers/openCodeParser
  */
 import { normalizeProviderUsage } from '../usageNormalization';
+import { ownValue } from '../ownKey';
 /**
  * OpenCode → Claude Code tool name mapping.
  * OpenCode uses lowercase names; downstream code expects PascalCase.
@@ -46,7 +47,7 @@ export function normalizeToolName(name) {
     if (!name)
         return name;
     // Check mapping (case-insensitive lookup via lowercase key)
-    const mapped = TOOL_NAME_MAP[name.toLowerCase()];
+    const mapped = ownValue(TOOL_NAME_MAP, name.toLowerCase());
     if (mapped)
         return mapped;
     // Already PascalCase (starts with uppercase)? Pass through.
@@ -115,6 +116,78 @@ function toISOString(time) {
         return time;
     return new Date(time).toISOString();
 }
+/**
+ * Token counts from a message in either storage shape: database rows are
+ * mapped to flat `cacheRead` / `cacheWrite`, while file-storage messages keep
+ * OpenCode's nested `cache: { read, write }`.
+ * @internal
+ */
+export function openCodeTokenCounts(tokens) {
+    const raw = (tokens ?? {});
+    const cache = (raw.cache ?? {});
+    const num = (value) => (typeof value === 'number' ? value : undefined);
+    return {
+        input: num(raw.input),
+        output: num(raw.output),
+        reasoning: num(raw.reasoning),
+        cacheRead: num(raw.cacheRead) ?? num(cache.read),
+        cacheWrite: num(raw.cacheWrite) ?? num(cache.write),
+        total: num(raw.total),
+    };
+}
+/**
+ * How a stored OpenCode message splits its tokens. Current OpenCode stores
+ * every bucket disjoint for every provider: `input` excludes cache reads and
+ * writes (since 2025-11) and `output` excludes `reasoning` (since 2026-04),
+ * with `total` equal to their sum. Older messages either counted cached input
+ * in `input` (OpenAI-compatible providers) or reasoning in `output`. The
+ * stored `total` tells the layouts apart; without it the current layout is
+ * assumed.
+ * @internal
+ */
+export function openCodeTokenLayout(tokens) {
+    const n = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+    const input = n(tokens.input);
+    const output = n(tokens.output);
+    const reasoning = n(tokens.reasoning);
+    const cache = n(tokens.cacheRead) + n(tokens.cacheWrite);
+    const total = n(tokens.total);
+    if (total > 0 && total !== input + cache + output + reasoning) {
+        if (reasoning > 0 && total === input + cache + output) {
+            return { inputIncludesCache: false, reasoningInOutput: true };
+        }
+        if (cache > 0 && total === input + output + reasoning) {
+            return { inputIncludesCache: true, reasoningInOutput: false };
+        }
+        if (cache > 0 && reasoning > 0 && total === input + output) {
+            return { inputIncludesCache: true, reasoningInOutput: true };
+        }
+    }
+    return { inputIncludesCache: false, reasoningInOutput: false };
+}
+/** Normalizes one OpenCode message's or step's stored tokens. @internal */
+export function normalizeOpenCodeUsage(tokens, providerID, extra = {}) {
+    const layout = openCodeTokenLayout(tokens);
+    return normalizeProviderUsage({
+        // `openai` semantics subtract cache reads from input; only an old
+        // cache-inclusive message needs that.
+        semantics: layout.inputIncludesCache
+            ? 'openai'
+            : providerID === 'anthropic'
+                ? 'anthropic'
+                : 'sidekick',
+        provider: providerID ?? 'opencode',
+        ...(extra.source ? { source: extra.source } : {}),
+        ...(extra.model ? { model: extra.model } : {}),
+        inputTokens: tokens.input,
+        outputTokens: tokens.output,
+        cacheReadTokens: tokens.cacheRead,
+        cacheWriteTokens: tokens.cacheWrite,
+        reasoningTokens: tokens.reasoning,
+        reasoningIncludedInOutput: layout.reasoningInOutput,
+        ...(extra.reportedCostUsd !== undefined ? { reportedCostUsd: extra.reportedCostUsd } : {}),
+    });
+}
 /**
  * Converts an OpenCode message and its parts into SessionEvent array.
  *
@@ -320,31 +393,20 @@ function convertAssistantMessage(message, parts) {
         : stepFinishCost > 0
             ? stepFinishCost
             : undefined;
-    const usage = {
-        input_tokens: message.tokens.input || 0,
-        output_tokens: message.tokens.output || 0,
-        cache_creation_input_tokens: message.tokens.cacheWrite || 0,
-        cache_read_input_tokens: message.tokens.cacheRead || 0,
-        reported_cost: reportedCost,
-        reasoning_tokens: message.tokens.reasoning || 0,
-    };
-    const normalizedUsage = normalizeProviderUsage({
-        semantics: message.providerID === 'openai'
-            ? 'openai'
-            : message.providerID === 'anthropic'
-                ? 'anthropic'
-                : 'sidekick',
-        provider: message.providerID ?? 'opencode',
+    const counts = openCodeTokenCounts(message.tokens);
+    const normalizedUsage = normalizeOpenCodeUsage(counts, message.providerID, {
         source: 'opencode-message',
         model: message.modelID,
-        inputTokens: message.tokens.input,
-        outputTokens: message.tokens.output,
-        cacheReadTokens: message.tokens.cacheRead,
-        cacheWriteTokens: message.tokens.cacheWrite,
-        reasoningTokens: message.tokens.reasoning,
-        reasoningIncludedInOutput: message.providerID === 'openai',
         reportedCostUsd: reportedCost,
     });
+    const usage = {
+        input_tokens: normalizedUsage.uncachedInputTokens,
+        output_tokens: counts.output || 0,
+        cache_creation_input_tokens: counts.cacheWrite || 0,
+        cache_read_input_tokens: counts.cacheRead || 0,
+        reported_cost: reportedCost,
+        reasoning_tokens: counts.reasoning || 0,
+    };
     const timestamp = toISOString(message.time.completed || message.time.created);
     const retryAttempts = parts
         .filter((part) => part.type === 'retry')
@@ -483,6 +545,7 @@ export function parseDbMessageData(row) {
             cacheRead: cache?.read || 0,
             cacheWrite: cache?.write || 0,
             reasoning: tokens?.reasoning || 0,
+            ...(typeof tokens?.total === 'number' ? { total: tokens.total } : {}),
         },
         time: {
             created: time?.created || row.time_created,

package/dist/esm/parsers/subagentScanner.js

@@ -12,28 +12,49 @@ import * as path from 'path';
 import { ClaudeUsageDeduper, dedupedRawClaudeUsage } from '../usage/claudeUsageDedupe';
 import { addUsageToSubagent } from '../usage/subagentUsage';
 import { cachedSubagentStats } from './subagentStatsCache';
+import { isSubagentSpawnTool } from '../subagentSpawn';
 /**
  * Pattern for matching subagent JSONL files.
  * Files are named like: agent-<hash>.jsonl
  */
 const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
+function metaString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
 /**
  * Reads `agent-<id>.meta.json` (written by Claude Code next to the transcript)
- * for the spawn's agent type and description. Missing or malformed files
- * yield an empty object.
+ * for the spawn's agent type, description, spawning tool_use id, parent agent,
+ * and completion flags. Missing or malformed files yield an empty object;
+ * wrongly typed fields are left out.
  */
 export function readAgentMeta(agentFilePath) {
     try {
         const metaPath = agentFilePath.replace(/\.jsonl$/, '.meta.json');
         const parsed = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-        return {
-            ...(typeof parsed.agentType === 'string' && parsed.agentType
-                ? { agentType: parsed.agentType }
-                : {}),
-            ...(typeof parsed.description === 'string' && parsed.description
-                ? { description: parsed.description }
-                : {}),
-        };
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        const record = parsed;
+        const meta = {};
+        const agentType = metaString(record.agentType);
+        if (agentType)
+            meta.agentType = agentType;
+        const description = metaString(record.description);
+        if (description)
+            meta.description = description;
+        const toolUseId = metaString(record.toolUseId);
+        if (toolUseId)
+            meta.toolUseId = toolUseId;
+        const parentAgentId = metaString(record.parentAgentId);
+        if (parentAgentId)
+            meta.parentAgentId = parentAgentId;
+        const requestShape = metaString(record.requestShape);
+        if (requestShape)
+            meta.requestShape = requestShape;
+        if (typeof record.finished === 'boolean')
+            meta.finished = record.finished;
+        if (typeof record.stoppedByUser === 'boolean')
+            meta.stoppedByUser = record.stoppedByUser;
+        return meta;
     }
     catch {
         return {};
@@ -208,8 +229,8 @@ function parseAgentFile(filePath, agentId, log) {
                                 }
                             }
                             toolCalls.push(toolCall);
-                            // If this is a Task tool call (spawning another subagent), extract info
-                            if (toolUse.name === 'Task' && toolUse.input) {
+                            // If this is an Agent/Task call (spawning another subagent), extract info
+                            if (isSubagentSpawnTool(toolUse.name) && toolUse.input) {
                                 if (toolUse.input.subagent_type && !agentType) {
                                     agentType = String(toolUse.input.subagent_type);
                                 }

package/dist/esm/parsers/subagentTraceParser.js

@@ -5,10 +5,13 @@
  * (not just stats) for drill-down trace visualization. Applies noise classification
  * and tool summary formatting from the formatters module.
  *
- * Three-phase parent-child linking:
- * 1. Result-based: match toolUseResult.agentId → parent tool_use_id
- * 2. Team summary: parse <teammate-message> XML blocks
- * 3. Positional fallback: timestamp ordering + proximity
+ * Parent-child linking, exact links first:
+ * 1. Meta `parentAgentId` (Claude Code writes it for nested spawns)
+ * 2. The child's spawning tool_use id (meta `toolUseId`) found in another
+ *    trace's `Agent` / `Task` calls
+ * Only traces without that spawn metadata (older Claude Code) fall back to:
+ * 3. Team summary: parse <teammate-message> XML blocks
+ * 4. Positional fallback: timestamp ordering + proximity
  *
  * @module parsers/subagentTraceParser
  */
@@ -19,6 +22,8 @@ import { isHardNoise, classifyMessage, getSoftNoiseReason } from '../formatters/
 import { ClaudeUsageDeduper, dedupedRawClaudeUsage } from '../usage/claudeUsageDedupe';
 import { addUsageToSubagent } from '../usage/subagentUsage';
 import { readAgentMeta } from './subagentScanner';
+import { isSubagentSpawnTool } from '../subagentSpawn';
+import { ownValue } from '../ownKey';
 // ── Constants ──
 const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
 // ── Public API ──
@@ -50,10 +55,8 @@ export function scanSubagentTraces(sessionDir, sessionId) {
             if (trace)
                 traces.push(trace);
         }
-        // Link parent-child relationships
-        linkTraces(traces);
-        // Return only top-level traces (those without parents)
-        return traces.filter((t) => !t.parentToolUseId);
+        // Link parent-child relationships; returns the traces with no parent agent.
+        return linkTraces(traces);
     }
     catch {
         return [];
@@ -133,8 +136,8 @@ function parseAgentTrace(filePath, agentId) {
                                 input: block.input || {},
                                 timestamp,
                             });
-                            // Extract agent info from Task tool
-                            if (block.name === 'Task' && block.input) {
+                            // Extract agent info from an Agent/Task spawn
+                            if (isSubagentSpawnTool(block.name) && block.input) {
                                 if (block.input.subagent_type && !agentType) {
                                     agentType = String(block.input.subagent_type);
                                 }
@@ -171,6 +174,14 @@ function parseAgentTrace(filePath, agentId) {
             agentId,
             agentType,
             description,
+            filePath,
+            ...(meta.toolUseId
+                ? { spawnToolUseId: meta.toolUseId, parentToolUseId: meta.toolUseId }
+                : {}),
+            ...(meta.parentAgentId ? { parentAgentId: meta.parentAgentId } : {}),
+            ...(meta.requestShape ? { background: meta.requestShape === 'background' } : {}),
+            ...(meta.finished !== undefined ? { finished: meta.finished } : {}),
+            ...(meta.stoppedByUser !== undefined ? { stoppedByUser: meta.stoppedByUser } : {}),
             events,
             children: [],
             stats: {
@@ -195,23 +206,61 @@ function parseAgentTrace(filePath, agentId) {
     }
 }
 // ── Parent-Child Linking ──
+/**
+ * Nests child traces under their parents and returns the traces with no
+ * parent agent. Exact metadata links come first; the heuristics only place
+ * traces Claude Code recorded no spawn metadata for.
+ */
 function linkTraces(traces) {
     const traceById = new Map();
     for (const trace of traces) {
         traceById.set(trace.agentId, trace);
     }
-    // Phase 1: Result-based linking
-    // Look for tool_result events that contain agentId references
+    const parentOf = new Map();
+    const attach = (parent, child) => {
+        if (parent === child || parentOf.has(child))
+            return false;
+        // Never nest an agent under its own descendant (malformed metadata).
+        for (let up = parent; up; up = parentOf.get(up)) {
+            if (up === child)
+                return false;
+        }
+        parentOf.set(child, parent);
+        parent.children.push(child);
+        return true;
+    };
+    // Phase 1: the meta file names the parent agent
+    for (const child of traces) {
+        const parent = child.parentAgentId ? traceById.get(child.parentAgentId) : undefined;
+        if (parent)
+            attach(parent, child);
+    }
+    // Phase 2: the child's spawning call is in another trace
+    const spawnOwner = new Map();
     for (const trace of traces) {
-        for (const traceEvent of trace.events) {
-            const evt = traceEvent.event;
-            if (evt.type === 'tool_use' && evt.tool?.name === 'Task') {
-                // The tool_use_id from this call should appear as a result in the parent
-                // but we can link via timestamp proximity to child traces
-            }
+        for (const id of spawnToolUseIdsOf(trace)) {
+            if (!spawnOwner.has(id))
+                spawnOwner.set(id, trace);
         }
     }
-    // Phase 2: Team summary linking
+    for (const child of traces) {
+        if (parentOf.has(child) || !child.spawnToolUseId)
+            continue;
+        const parent = spawnOwner.get(child.spawnToolUseId);
+        if (parent && attach(parent, child))
+            child.parentAgentId ??= parent.agentId;
+    }
+    // Heuristic links set parentAgentId and, as before, parentToolUseId to the
+    // parent's agent id.
+    const unresolved = (trace) => !parentOf.has(trace) && !trace.spawnToolUseId && !trace.parentAgentId;
+    const linkHeuristically = (parent, child) => {
+        if (!attach(parent, child))
+            return false;
+        child.parentAgentId = parent.agentId;
+        child.parentToolUseId = parent.agentId;
+        return true;
+    };
+    // Phase 3: Team summary linking
     for (const trace of traces) {
         for (const traceEvent of trace.events) {
             const content = traceEvent.event.message?.content;
@@ -219,45 +268,56 @@ function linkTraces(traces) {
                 // Parse teammate agent IDs from XML blocks
                 const matches = content.matchAll(/agent[_-]id['":\s]+([a-f0-9]+)/gi);
                 for (const match of matches) {
-                    const childId = match[1];
-                    const child = traceById.get(childId);
-                    if (child && child !== trace && !child.parentToolUseId) {
-                        child.parentToolUseId = trace.agentId;
-                        trace.children.push(child);
-                    }
+                    const child = traceById.get(match[1]);
+                    if (child && unresolved(child))
+                        linkHeuristically(trace, child);
                 }
             }
         }
     }
-    // Phase 3: Positional fallback — timestamp proximity
+    // Phase 4: Positional fallback — timestamp proximity
     // Traces without parents that fall within another trace's time window
-    const parentless = traces.filter((t) => !t.parentToolUseId);
-    for (const child of parentless) {
+    for (const child of traces.filter(unresolved)) {
         if (!child.stats.startTime)
             continue;
         const childStart = child.stats.startTime.getTime();
-        // Find a trace that was active (Task tool call) right before this child started
+        // Find a top-level trace that spawned an agent right before this child started
         for (const potential of traces) {
-            if (potential === child)
+            if (potential === child || parentOf.has(potential))
                 continue;
-            if (potential.parentToolUseId)
-                continue; // Already linked
             for (const traceEvent of potential.events) {
                 const evt = traceEvent.event;
-                if (evt.type === 'assistant' && evt.tool?.name === 'Task') {
+                if (evt.type === 'assistant' && isSubagentSpawnTool(evt.tool?.name)) {
                     const taskTime = new Date(evt.timestamp).getTime();
                     // Within 2 seconds before child start
                     if (taskTime <= childStart && childStart - taskTime < 2000) {
-                        child.parentToolUseId = potential.agentId;
-                        potential.children.push(child);
+                        linkHeuristically(potential, child);
                         break;
                     }
                 }
             }
-            if (child.parentToolUseId)
+            if (parentOf.has(child))
                 break;
         }
     }
+    return traces.filter((trace) => !parentOf.has(trace));
+}
+/** Ids of the `Agent` / `Task` calls a trace made. */
+function spawnToolUseIdsOf(trace) {
+    const ids = [];
+    for (const traceEvent of trace.events) {
+        const content = traceEvent.event.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type === 'tool_use' &&
+                typeof block.id === 'string' &&
+                isSubagentSpawnTool(block.name)) {
+                ids.push(block.id);
+            }
+        }
+    }
+    return ids;
 }
 // ── Helpers ──
 function rawToSessionEvent(raw) {
@@ -272,7 +332,7 @@ function rawToSessionEvent(raw) {
         tool_result: 'tool_result',
         summary: 'summary',
     };
-    const mappedType = typeMap[type];
+    const mappedType = ownValue(typeMap, type);
     if (!mappedType)
         return null;
     const message = raw.message;

package/dist/esm/pricing.js

@@ -0,0 +1,18 @@
+/**
+ * `sidekick-shared/pricing` — model pricing, model-id identity, usage
+ * normalization and cost, cost provenance, cost/token formatting, and text
+ * token estimates, as one small pure entry (no filesystem, network, or Zod).
+ *
+ * For hosts that price usage or format costs without session reading: it
+ * loads a handful of modules instead of the full browser surface. LiteLLM
+ * catalog hydration stays Node-only in `sidekick-shared/node`
+ * (`hydratePricingCatalog`); once hydrated, lookups here see the catalog.
+ * Everything here is also exported from the package root and
+ * `sidekick-shared/browser`.
+ *
+ * @module pricing
+ */
+export { MODEL_PROVIDER_IDS, canonicalModelId, isMovingModelAlias, parseModelId, compareModelIds, sortModelIds, shortModelName, getModelDisplayInfo, getModelInfo, getModelPricing, resolveModelPricing, registerModelPricing, clearRegisteredModelPricing, getPricingCatalogInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, costSourceFromPricingProvenance, mergeCostComponents, formatCost, } from './modelInfo';
+export { normalizeProviderUsage, extractNormalizedUsage, calculateNormalizedUsageCost, } from './usageNormalization';
+export { formatTokenCount, formatDurationMs } from './formatting';
+export { ASCII_CHARS_PER_TOKEN, estimateTextTokens, estimateSerializedTokens, } from './tokenEstimation';

package/dist/esm/pricingCatalog.js

@@ -19,7 +19,8 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { _setCatalogContextWindows } from './modelContext';
-import { _setPricingOverrides } from './modelInfo';
+import { _setPricingOverrides, getPricingCatalogInfo } from './modelInfo';
+import { setOwnValue } from './ownKey';
 import { getConfigDir } from './paths';
 import { atomicWriteJson } from './writers/atomic';
 // ── Constants ──
@@ -36,6 +37,10 @@ const DEFAULT_TIMEOUT_MS = 3_000;
  *   2. Otherwise attempt a network fetch; on success, persist + apply.
  *   3. On any failure, load a stale cache if present; else leave overrides empty.
  *
+ * `getPricingCatalogInfo().source` afterwards reads `litellm` for a fresh fetch
+ * or a cache within `ttlMs`, and `stale-cache` for a cache older than `ttlMs`
+ * — whether the refresh failed or `offline` skipped it.
+ *
  * Always resolves — never throws. Offline-safe.
  */
 export async function hydratePricingCatalog(options = {}) {
@@ -44,8 +49,9 @@ export async function hydratePricingCatalog(options = {}) {
     const now = Date.now();
     // 1. Fresh cache? (Offline callers take any cache, however old.)
     const cached = await readCache(cachePath);
-    if (cached && (offline || now - Date.parse(cached.fetchedAt) < ttlMs)) {
-        return applyCacheFile(cached, 'cache');
+    const cacheFresh = cached !== null && now - Date.parse(cached.fetchedAt) < ttlMs;
+    if (cached && (offline || cacheFresh)) {
+        return applyCacheFile(cached, 'cache', cacheFresh ? 'litellm' : 'stale-cache');
     }
     // 2. Try network.
     if (fetchImpl && !offline) {
@@ -58,12 +64,12 @@ export async function hydratePricingCatalog(options = {}) {
                 contextWindows: normalizeLiteLlmContextWindows(fetched),
             };
             await writeCache(cachePath, payload, logger);
-            return applyCacheFile(payload, 'network');
+            return applyCacheFile(payload, 'network', 'litellm');
         }
     }
     // 3. Fall back to stale cache if present.
     if (cached) {
-        return applyCacheFile(cached, 'cache');
+        return applyCacheFile(cached, 'cache', 'stale-cache');
     }
     // 4. Nothing we can do — stay on static tables.
     return {
@@ -71,6 +77,7 @@ export async function hydratePricingCatalog(options = {}) {
         entries: 0,
         contextWindowEntries: 0,
         fetchedAt: new Date(now).toISOString(),
+        digest: getPricingCatalogInfo().digest,
     };
 }
 /**
@@ -78,9 +85,9 @@ export async function hydratePricingCatalog(options = {}) {
  * `contextWindows` is absent on caches written before context hydration; those
  * contribute no overrides rather than clearing whatever is already loaded.
  */
-function applyCacheFile(cache, source) {
+function applyCacheFile(cache, source, basis) {
     const contextWindows = cache.contextWindows ?? {};
-    _setPricingOverrides(cache.overrides);
+    _setPricingOverrides(cache.overrides, { source: basis, fetchedAt: cache.fetchedAt });
     if (Object.keys(contextWindows).length > 0) {
         _setCatalogContextWindows(contextWindows);
     }
@@ -89,6 +96,7 @@ function applyCacheFile(cache, source) {
         entries: Object.keys(cache.overrides).length,
         contextWindowEntries: Object.keys(contextWindows).length,
         fetchedAt: cache.fetchedAt,
+        digest: getPricingCatalogInfo().digest,
     };
 }
 /**
@@ -110,7 +118,7 @@ export function normalizeLiteLlmCatalog(raw) {
             continue;
         // Catalog keys use both `provider/model` and bare `model` forms. Record both
         // the raw key and the bare-model form so lookups work regardless of caller.
-        out[key] = pricing;
+        setOwnValue(out, key, pricing);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key && !out[bare]) {
             out[bare] = pricing;
@@ -147,7 +155,7 @@ export function normalizeLiteLlmContextWindows(raw) {
         const window = entry.max_input_tokens;
         if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
             continue;
-        out[key] = window;
+        setOwnValue(out, key, window);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key) {
             const seen = aliasWindows.get(bare) ?? new Set();