feat: enhance usage analytics dashboard (#666)

- visualize input, output, and cache token segments in usage charts
- add usage period selector for 7d, 30d, 90d, and 365d
- guard usage stats against stale overlapping period requests
- normalize blank model usage into unknown buckets
- add client and server coverage for usage analytics behavior

packages/client/src/components/hermes/usage/DailyTrend.vue

@@ -25,7 +25,7 @@ function cacheHitRate(d: { input_tokens: number; cache_read_tokens: number }): s
 }
 
 const maxTokens = computed(() =>
-  Math.max(...usageStore.dailyUsage.map(d => d.input_tokens + d.output_tokens), 1),
+  Math.max(...usageStore.dailyUsage.map(d => d.visualTokens), 1),
 )
 </script>
 
@@ -41,12 +41,25 @@ const maxTokens = computed(() =>
       >
         <div class="bar-track">
           <div
-            class="bar-fill"
+            class="bar-stack"
-            :style="{
+            :style="{ height: (d.visualTokens / maxTokens * 100) + '%' }"
-              height: ((d.input_tokens + d.output_tokens) / maxTokens * 100) + '%',
+          >
-              '--output-pct': (d.output_tokens / Math.max(d.input_tokens + d.output_tokens, 1) * 100) + '%',
+            <div
-            }"
+              v-if="d.output_tokens > 0"
-          />
+              class="bar-segment output"
+              :style="{ height: d.outputPercent + '%' }"
+            />
+            <div
+              v-if="d.input_tokens > 0"
+              class="bar-segment input"
+              :style="{ height: d.inputPercent + '%' }"
+            />
+            <div
+              v-if="d.cache_read_tokens > 0"
+              class="bar-segment cache"
+              :style="{ height: d.cachePercent + '%' }"
+            />
+          </div>
         </div>
         <div class="bar-tooltip">
           <div class="tooltip-date">{{ d.date }}</div>
@@ -65,6 +78,12 @@ const maxTokens = computed(() =>
       <span>{{ usageStore.dailyUsage[usageStore.dailyUsage.length - 1]?.date.slice(5) }}</span>
     </div>
 
+    <div class="chart-legend" aria-label="Token type legend">
+      <div class="legend-item"><span class="legend-swatch input" />{{ t('usage.inputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch output" />{{ t('usage.outputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch cache" />{{ t('usage.cacheRead') }}</div>
+    </div>
+
     <div class="trend-table">
       <table>
         <thead>
@@ -80,7 +99,7 @@ const maxTokens = computed(() =>
           </tr>
         </thead>
         <tbody>
-          <tr v-for="d in [...usageStore.dailyUsage].reverse().slice(0, 30)" :key="d.date">
+          <tr v-for="d in [...usageStore.dailyUsage].reverse()" :key="d.date">
             <td>{{ d.date }}</td>
             <td>{{ formatTokens(d.input_tokens) }}</td>
             <td>{{ formatTokens(d.output_tokens) }}</td>
@@ -135,21 +154,38 @@ const maxTokens = computed(() =>
   border-radius: 2px 2px 0 0;
   display: flex;
   align-items: flex-end;
+  overflow: hidden;
+  position: relative;
 }
 
-.bar-fill {
+.bar-stack {
+  width: 100%;
+  display: flex;
+  flex-direction: column-reverse;
+  justify-content: flex-start;
+  overflow: hidden;
+  transition: height 0.3s ease;
+}
+
+.bar-segment {
   width: 100%;
-  border-radius: 2px 2px 0 0;
   min-height: 0;
   transition: height 0.3s ease;
-  /* Bottom = output (teal), top = input (blue) */
+}
-  background: linear-gradient(
+
-    to top,
+.bar-segment.output,
-    #26a69a 0%,
+.legend-swatch.output {
-    #26a69a var(--output-pct, 50%),
+  background: #26a69a;
-    #5c6bc0 var(--output-pct, 50%),
+}
-    #5c6bc0 100%
+
-  );
+.bar-segment.input,
+.legend-swatch.input {
+  background: #5c6bc0;
+}
+
+.bar-segment.cache,
+.legend-swatch.cache {
+  background: #f6ad55;
 }
 
 .bar-tooltip {
@@ -184,12 +220,10 @@ const maxTokens = computed(() =>
 
 .tooltip-date {
   font-weight: 600;
-  margin-bottom: 2px;
+  margin-bottom: 4px;
 }
 
 .tooltip-row {
-  font-size: 10px;
-  opacity: 0.85;
   line-height: 1.5;
 }
 
@@ -198,46 +232,59 @@ const maxTokens = computed(() =>
   justify-content: space-between;
   font-size: 10px;
   color: $text-muted;
-  margin-top: 4px;
+  margin-bottom: 12px;
-  margin-bottom: 16px;
+}
+
+.chart-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 14px;
+  margin: 0 0 16px;
+  color: $text-muted;
+  font-size: 11px;
+}
+
+.legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.legend-swatch {
+  width: 8px;
+  height: 8px;
+  border-radius: 2px;
+  flex-shrink: 0;
 }
 
 .trend-table {
   overflow-x: auto;
-}
 
-table {
+  table {
-  width: 100%;
+    width: 100%;
-  border-collapse: collapse;
+    border-collapse: collapse;
-  font-size: 12px;
+    font-size: 11px;
-}
+  }
 
-thead {
+  th,
-  position: sticky;
+  td {
-  top: 0;
+    text-align: right;
-}
+    padding: 6px 8px;
+    border-bottom: 1px solid $border-color;
+  }
 
-th {
+  th:first-child,
-  text-align: left;
+  td:first-child {
-  padding: 8px 10px;
+    text-align: left;
-  font-weight: 600;
+  }
-  color: $text-muted;
-  border-bottom: 1px solid $border-color;
-  background: $bg-card;
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-}
 
-td {
+  th {
-  padding: 6px 10px;
+    color: $text-muted;
-  color: $text-secondary;
+    font-weight: 500;
-  border-bottom: 1px solid $border-light;
+  }
-  font-family: $font-code;
-  font-size: 11px;
-}
 
-tr:last-child td {
+  td {
-  border-bottom: none;
+    color: $text-secondary;
+  }
 }
 </style>

packages/client/src/components/hermes/usage/ModelBreakdown.vue

@@ -5,28 +5,61 @@ import { useUsageStore } from '@/stores/hermes/usage'
 
 const { t } = useI18n()
 const usageStore = useUsageStore()
-const maxModelTokens = computed(() => Math.max(usageStore.modelUsage[0]?.totalTokens || 0, 1))
+const maxModelTokens = computed(() => Math.max(...usageStore.modelUsage.map(m => m.visualTokens), 1))
 
 function formatTokens(n: number): string {
   if (n >= 1000000) return (n / 1000000).toFixed(1) + 'M'
   if (n >= 1000) return (n / 1000).toFixed(1) + 'K'
   return String(n)
 }
+
+function cacheHitRate(m: { inputTokens: number; cacheTokens: number }): string {
+  const total = m.inputTokens + m.cacheTokens
+  if (total === 0) return '--'
+  return ((m.cacheTokens / total) * 100).toFixed(1) + '%'
+}
 </script>
 
 <template>
   <div class="model-breakdown">
     <h3 class="section-title">{{ t('usage.modelBreakdown') }}</h3>
+
+    <div class="model-legend" aria-label="Token type legend">
+      <div class="legend-item"><span class="legend-swatch input" />{{ t('usage.inputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch output" />{{ t('usage.outputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch cache" />{{ t('usage.cacheRead') }}</div>
+    </div>
+
     <div class="model-list">
       <div v-for="m in usageStore.modelUsage" :key="m.model" class="model-row">
-        <span class="model-name">{{ m.model }}</span>
+        <span class="model-swatch" :style="{ background: m.color }" />
+        <span class="model-name" :title="m.model">{{ m.model }}</span>
         <div class="model-bar-wrap">
           <div
             class="model-bar"
-            :style="{ width: (m.totalTokens / maxModelTokens * 100) + '%' }"
+            :style="{ width: (m.visualTokens / maxModelTokens * 100) + '%' }"
-          />
+          >
+            <div
+              v-if="m.inputTokens > 0"
+              class="model-bar-segment input"
+              :style="{ width: m.inputPercent + '%' }"
+            />
+            <div
+              v-if="m.outputTokens > 0"
+              class="model-bar-segment output"
+              :style="{ width: m.outputPercent + '%' }"
+            />
+            <div
+              v-if="m.cacheTokens > 0"
+              class="model-bar-segment cache"
+              :style="{ width: m.cachePercent + '%' }"
+            />
+          </div>
         </div>
-        <span class="model-tokens">{{ formatTokens(m.totalTokens) }}</span>
+        <span class="model-tokens" :title="`${t('usage.inputTokens')}: ${formatTokens(m.inputTokens)} · ${t('usage.outputTokens')}: ${formatTokens(m.outputTokens)} · ${t('usage.cacheRead')}: ${formatTokens(m.cacheTokens)} · ${t('usage.cacheHitRate')}: ${cacheHitRate(m)}`">
+          {{ formatTokens(m.totalTokens) }}
+          <small v-if="m.cacheTokens > 0">+{{ formatTokens(m.cacheTokens) }}</small>
+        </span>
       </div>
     </div>
   </div>
@@ -50,6 +83,44 @@ function formatTokens(n: number): string {
   margin: 0 0 12px;
 }
 
+.model-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 14px;
+  margin: 0 0 12px;
+  color: $text-muted;
+  font-size: 11px;
+}
+
+.legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.legend-swatch,
+.model-swatch {
+  width: 8px;
+  height: 8px;
+  border-radius: 2px;
+  flex-shrink: 0;
+}
+
+.legend-swatch.input,
+.model-bar-segment.input {
+  background: #5c6bc0;
+}
+
+.legend-swatch.output,
+.model-bar-segment.output {
+  background: #26a69a;
+}
+
+.legend-swatch.cache,
+.model-bar-segment.cache {
+  background: #f6ad55;
+}
+
 .model-list {
   display: flex;
   flex-direction: column;
@@ -83,21 +154,29 @@ function formatTokens(n: number): string {
 
 .model-bar {
   height: 100%;
-  background: $text-primary;
   border-radius: 3px;
   min-width: 2px;
   transition: width 0.3s ease;
+  display: flex;
+  overflow: hidden;
+}
 
-  .dark & {
+.model-bar-segment {
-    background: #66bb6a;
+  height: 100%;
-  }
+  min-width: 0;
 }
 
 .model-tokens {
   font-size: 12px;
   color: $text-muted;
-  width: 60px;
+  width: 86px;
   text-align: right;
   flex-shrink: 0;
+
+  small {
+    color: #f6ad55;
+    margin-left: 4px;
+    font-size: 10px;
+  }
 }
 </style>

packages/client/src/i18n/locales/de.ts

@@ -751,7 +751,7 @@ jobTriggered: 'Job ausgelost',
     estimatedCost: 'Gesch. Kosten',
     cacheHitRate: 'Cache-Trefferquote',
     modelBreakdown: 'Modellaufschluesselung',
-    dailyTrend: 'Tagliche Nutzung (letzte 30 Tage)',
+    dailyTrend: 'Tagliche Nutzung',
     date: 'Datum',
     tokens: 'Tokens',
     cache: 'Cache',

packages/client/src/i18n/locales/en.ts

@@ -973,7 +973,7 @@ export default {
     estimatedCost: 'Est. Cost',
     cacheHitRate: 'Cache Hit Rate',
     modelBreakdown: 'Model Breakdown',
-    dailyTrend: 'Daily Usage (Last 30 Days)',
+    dailyTrend: 'Daily Usage',
     date: 'Date',
     tokens: 'Tokens',
     cache: 'Cache',

packages/client/src/i18n/locales/es.ts

@@ -747,7 +747,7 @@ jobTriggered: 'Job ejecutado',
     estimatedCost: 'Costo est.',
     cacheHitRate: 'Tasa de acierto de cache',
     modelBreakdown: 'Desglose por modelo',
-    dailyTrend: 'Uso diario (ultimos 30 dias)',
+    dailyTrend: 'Uso diario',
     date: 'Fecha',
     tokens: 'Tokens',
     cache: 'Caché',

packages/client/src/i18n/locales/fr.ts

@@ -747,7 +747,7 @@ jobTriggered: 'Job declenche',
     estimatedCost: 'Cout est.',
     cacheHitRate: 'Taux de succes du cache',
     modelBreakdown: 'Repartition par modele',
-    dailyTrend: 'Utilisation quotidienne (30 derniers jours)',
+    dailyTrend: 'Utilisation quotidienne',
     date: 'Date',
     tokens: 'Jetons',
     cache: 'Cache',

packages/client/src/i18n/locales/ja.ts

@@ -747,7 +747,7 @@ export default {
     estimatedCost: '推定コスト',
     cacheHitRate: 'キャッシュヒット率',
     modelBreakdown: 'モデル別内訳',
-    dailyTrend: '日別使用量（過去30日間）',
+    dailyTrend: '日別使用量',
     date: '日付',
     tokens: 'トークン',
     cache: 'キャッシュ',

packages/client/src/i18n/locales/ko.ts

@@ -747,7 +747,7 @@ export default {
     estimatedCost: '예상 비용',
     cacheHitRate: '캐시 적중률',
     modelBreakdown: '모델별 분포',
-    dailyTrend: '일별 사용량 (최근 30일)',
+    dailyTrend: '일별 사용량',
     date: '날짜',
     tokens: '토큰',
     cache: '캐시',

packages/client/src/i18n/locales/pt.ts

@@ -747,7 +747,7 @@ jobTriggered: 'Job acionado',
     estimatedCost: 'Custo est.',
     cacheHitRate: 'Taxa de acerto de cache',
     modelBreakdown: 'Detalhamento por modelo',
-    dailyTrend: 'Uso diario (ultimos 30 dias)',
+    dailyTrend: 'Uso diario',
     date: 'Data',
     tokens: 'Tokens',
     cache: 'Cache',

packages/client/src/i18n/locales/zh-TW.ts

@@ -975,7 +975,7 @@ export default {
     estimatedCost: '預估費用',
     cacheHitRate: '快取命中率',
     modelBreakdown: '模型分布',
-    dailyTrend: '每日用量（近 30 天）',
+    dailyTrend: '每日用量',
     date: '日期',
     tokens: 'Token',
     cache: '快取',

packages/client/src/i18n/locales/zh.ts

@@ -975,7 +975,7 @@ export default {
     estimatedCost: '预估费用',
     cacheHitRate: '缓存命中率',
     modelBreakdown: '模型分布',
-    dailyTrend: '每日用量（近 30 天）',
+    dailyTrend: '每日用量',
     date: '日期',
     tokens: 'Token',
     cache: '缓存',

packages/client/src/stores/hermes/usage.ts

@@ -11,6 +11,10 @@ interface DailyUsage {
   sessions: number
   errors: number
   cost: number
+  visualTokens: number
+  inputPercent: number
+  outputPercent: number
+  cachePercent: number
 }
 
 interface ModelUsage {
@@ -18,22 +22,70 @@ interface ModelUsage {
   inputTokens: number
   outputTokens: number
   cacheTokens: number
+  cacheWriteTokens: number
   totalTokens: number
+  visualTokens: number
   sessions: number
+  color: string
+  inputPercent: number
+  outputPercent: number
+  cachePercent: number
+}
+
+const MODEL_COLORS = [
+  '#4fd1c5',
+  '#63b3ed',
+  '#f6ad55',
+  '#b794f4',
+  '#68d391',
+  '#fc8181',
+  '#f687b3',
+  '#90cdf4',
+  '#fbd38d',
+  '#9ae6b4',
+]
+
+function normalizeModel(model: string | null | undefined): string {
+  const trimmed = (model || '').trim()
+  return trimmed || 'unknown'
+}
+
+function percent(part: number, total: number): number {
+  if (total <= 0) return 0
+  return part / total * 100
+}
+
+function getModelColor(model: string): string {
+  const normalized = normalizeModel(model)
+  let hash = 0
+  for (let i = 0; i < normalized.length; i += 1) {
+    hash = ((hash << 5) - hash) + normalized.charCodeAt(i)
+    hash |= 0
+  }
+  return MODEL_COLORS[Math.abs(hash) % MODEL_COLORS.length]
 }
 
 export const useUsageStore = defineStore('usage', () => {
   const stats = ref<UsageStatsResponse | null>(null)
   const isLoading = ref(false)
+  let latestRequestId = 0
 
   async function loadSessions(days = 30) {
+    const requestId = ++latestRequestId
     isLoading.value = true
     try {
-      stats.value = await fetchUsageStats(days)
+      const response = await fetchUsageStats(days)
+      if (requestId === latestRequestId) {
+        stats.value = response
+      }
     } catch (err) {
-      console.error('Failed to load usage stats:', err)
+      if (requestId === latestRequestId) {
+        console.error('Failed to load usage stats:', err)
+      }
     } finally {
-      isLoading.value = false
+      if (requestId === latestRequestId) {
+        isLoading.value = false
+      }
     }
   }
 
@@ -56,17 +108,46 @@ export const useUsageStore = defineStore('usage', () => {
 
   const modelUsage = computed<ModelUsage[]>(() => {
     if (!stats.value) return []
-    return stats.value.model_usage.map(m => ({
+    return stats.value.model_usage.map(m => {
-      model: m.model || 'unknown',
+      const model = normalizeModel(m.model)
-      inputTokens: m.input_tokens,
+      const totalTokens = m.input_tokens + m.output_tokens
-      outputTokens: m.output_tokens,
+      const visualTokens = totalTokens + m.cache_read_tokens
-      cacheTokens: m.cache_read_tokens,
+      return {
-      totalTokens: m.input_tokens + m.output_tokens,
+        model,
-      sessions: m.sessions,
+        inputTokens: m.input_tokens,
-    })).sort((a, b) => b.totalTokens - a.totalTokens)
+        outputTokens: m.output_tokens,
+        cacheTokens: m.cache_read_tokens,
+        cacheWriteTokens: m.cache_write_tokens,
+        totalTokens,
+        visualTokens,
+        sessions: m.sessions,
+        color: getModelColor(model),
+        inputPercent: percent(m.input_tokens, visualTokens),
+        outputPercent: percent(m.output_tokens, visualTokens),
+        cachePercent: percent(m.cache_read_tokens, visualTokens),
+      }
+    }).sort((a, b) => b.visualTokens - a.visualTokens)
   })
 
-  const dailyUsage = computed<DailyUsage[]>(() => stats.value?.daily_usage ?? [])
+  const modelLegend = computed(() => {
+    const seen = new Set<string>()
+    return modelUsage.value.filter(m => {
+      if (seen.has(m.model)) return false
+      seen.add(m.model)
+      return true
+    }).map(m => ({ model: m.model, color: m.color }))
+  })
+
+  const dailyUsage = computed<DailyUsage[]>(() => (stats.value?.daily_usage ?? []).map(d => {
+    const visualTokens = d.input_tokens + d.output_tokens + d.cache_read_tokens
+    return {
+      ...d,
+      visualTokens,
+      inputPercent: percent(d.input_tokens, visualTokens),
+      outputPercent: percent(d.output_tokens, visualTokens),
+      cachePercent: percent(d.cache_read_tokens, visualTokens),
+    }
+  }))
 
   const avgSessionsPerDay = computed(() => {
     if (!stats.value || stats.value.daily_usage.length === 0) return 0
@@ -88,7 +169,9 @@ export const useUsageStore = defineStore('usage', () => {
     cacheHitRate,
     estimatedCost,
     modelUsage,
+    modelLegend,
     dailyUsage,
     avgSessionsPerDay,
+    getModelColor,
   }
 })

packages/client/src/views/hermes/UsageView.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { NButton } from 'naive-ui'
-import { onMounted } from 'vue'
+import { onMounted, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useUsageStore } from '@/stores/hermes/usage'
 import StatCards from '@/components/hermes/usage/StatCards.vue'
@@ -10,8 +10,22 @@ import DailyTrend from '@/components/hermes/usage/DailyTrend.vue'
 const { t } = useI18n()
 const usageStore = useUsageStore()
 
+const periodOptions = [
+  { label: '7d', days: 7 },
+  { label: '30d', days: 30 },
+  { label: '90d', days: 90 },
+  { label: '365d', days: 365 },
+] as const
+
+const selectedPeriod = ref(30)
+
+function loadUsage(days = selectedPeriod.value) {
+  selectedPeriod.value = days
+  usageStore.loadSessions(days)
+}
+
 onMounted(() => {
-  usageStore.loadSessions()
+  loadUsage(30)
 })
 </script>
 
@@ -19,9 +33,26 @@ onMounted(() => {
   <div class="usage-view">
     <header class="page-header">
       <h2 class="header-title">{{ t('usage.title') }}</h2>
-      <NButton size="small" quaternary :loading="usageStore.isLoading" @click="usageStore.loadSessions()">
+      <div class="usage-toolbar">
-        {{ t('usage.refresh') }}
+        <div class="period-selector" role="group" aria-label="Usage statistics period">
-      </NButton>
+          <NButton
+            v-for="option in periodOptions"
+            :key="option.days"
+            class="period-option"
+            size="small"
+            :type="selectedPeriod === option.days ? 'primary' : 'default'"
+            :secondary="selectedPeriod === option.days"
+            :quaternary="selectedPeriod !== option.days"
+            :aria-pressed="selectedPeriod === option.days"
+            @click="loadUsage(option.days)"
+          >
+            {{ option.label }}
+          </NButton>
+        </div>
+        <NButton class="refresh-button" size="small" quaternary :loading="usageStore.isLoading" @click="loadUsage()">
+          {{ t('usage.refresh') }}
+        </NButton>
+      </div>
     </header>
 
     <div class="usage-content">
@@ -51,6 +82,37 @@ onMounted(() => {
   flex-direction: column;
 }
 
+.page-header {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 21px 20px;
+  border-bottom: 1px solid $border-color;
+}
+
+.header-title {
+  margin: 0;
+  color: $text-primary;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.usage-toolbar,
+.period-selector {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.period-selector {
+  padding: 2px;
+  border: 1px solid $border-light;
+  border-radius: $radius-sm;
+  background: $bg-secondary;
+}
+
 .usage-content {
   flex: 1;
   overflow-y: auto;
@@ -73,4 +135,20 @@ onMounted(() => {
   color: $text-muted;
   font-size: 14px;
 }
+
+@media (max-width: $breakpoint-mobile) {
+  .page-header,
+  .usage-toolbar {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  .usage-toolbar {
+    width: 100%;
+  }
+
+  .period-selector {
+    flex-wrap: wrap;
+  }
+}
 </style>

packages/server/src/controllers/hermes/sessions.ts

@@ -450,8 +450,9 @@ export async function usageStats(ctx: any) {
   const totalSessions = local.sessions + hermes.sessions
 
   const modelMap = new Map<string, UsageStatsModelRow>()
-  for (const m of [...local.by_model, ...hermes.by_model].filter(m => m.model)) {
+  for (const m of [...local.by_model, ...hermes.by_model]) {
-    const existing = modelMap.get(m.model)
+    const model = (m.model || '').trim() || 'unknown'
+    const existing = modelMap.get(model)
     if (existing) {
       existing.input_tokens += m.input_tokens
       existing.output_tokens += m.output_tokens
@@ -460,7 +461,7 @@ export async function usageStats(ctx: any) {
       existing.reasoning_tokens += m.reasoning_tokens
       existing.sessions += m.sessions
     } else {
-      modelMap.set(m.model, { ...m })
+      modelMap.set(model, { ...m, model })
     }
   }
 

tests/client/usage-components-cache-visuals.test.ts

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+
+const mockUsageStore = vi.hoisted(() => ({
+  dailyUsage: [
+    {
+      date: '2026-05-12',
+      input_tokens: 100,
+      output_tokens: 50,
+      cache_read_tokens: 75,
+      cache_write_tokens: 10,
+      sessions: 2,
+      errors: 0,
+      cost: 0.02,
+      visualTokens: 225,
+      inputPercent: 44.444,
+      outputPercent: 22.222,
+      cachePercent: 33.333,
+    },
+  ],
+  modelUsage: [
+    {
+      model: 'gpt-5',
+      inputTokens: 100,
+      outputTokens: 50,
+      cacheTokens: 75,
+      cacheWriteTokens: 10,
+      totalTokens: 150,
+      visualTokens: 225,
+      sessions: 2,
+      color: '#4fd1c5',
+      inputPercent: 44.444,
+      outputPercent: 22.222,
+      cachePercent: 33.333,
+    },
+  ],
+}))
+
+vi.mock('@/stores/hermes/usage', () => ({
+  useUsageStore: () => mockUsageStore,
+}))
+
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({
+    t: (key: string) => key,
+  }),
+}))
+
+import DailyTrend from '@/components/hermes/usage/DailyTrend.vue'
+import ModelBreakdown from '@/components/hermes/usage/ModelBreakdown.vue'
+
+describe('usage cache visualizations', () => {
+  it('renders cache-read as a visible segment in the daily usage bars', () => {
+    const wrapper = mount(DailyTrend)
+
+    const cacheSegment = wrapper.find('.bar-segment.cache')
+    expect(cacheSegment.exists()).toBe(true)
+    expect(cacheSegment.attributes('style')).toContain('height: 33.333%')
+    expect(wrapper.text()).toContain('usage.cacheRead')
+  })
+
+  it('renders model breakdown as input/output/cache stacked segments', () => {
+    const wrapper = mount(ModelBreakdown)
+
+    expect(wrapper.find('.model-swatch').attributes('style')).toContain('background: rgb(79, 209, 197)')
+    expect(wrapper.find('.model-bar-segment.input').exists()).toBe(true)
+    expect(wrapper.find('.model-bar-segment.output').exists()).toBe(true)
+    const cacheSegment = wrapper.find('.model-bar-segment.cache')
+    expect(cacheSegment.exists()).toBe(true)
+    expect(cacheSegment.attributes('style')).toContain('width: 33.333%')
+  })
+})

tests/client/usage-store.test.ts

@@ -10,6 +10,21 @@ vi.mock('@/api/hermes/sessions', () => ({
   fetchUsageStats: usageApiMock.fetchUsageStats,
 }))
 
+function emptyStats(totalSessions = 0, periodDays = 30) {
+  return {
+    total_input_tokens: totalSessions,
+    total_output_tokens: 0,
+    total_cache_read_tokens: 0,
+    total_cache_write_tokens: 0,
+    total_reasoning_tokens: 0,
+    total_cost: 0,
+    total_sessions: totalSessions,
+    period_days: periodDays,
+    model_usage: [],
+    daily_usage: [],
+  }
+}
+
 describe('usage store analytics adapter', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
@@ -31,8 +46,8 @@ describe('usage store analytics adapter', () => {
         { model: '', input_tokens: 20, output_tokens: 10, cache_read_tokens: 5, cache_write_tokens: 2, reasoning_tokens: 3, sessions: 1 },
       ],
       daily_usage: [
-        { date: '2026-04-29', tokens: 100, cache: 20, sessions: 1, cost: 0.01 },
+        { date: '2026-04-29', input_tokens: 80, output_tokens: 20, cache_read_tokens: 40, cache_write_tokens: 4, sessions: 1, errors: 0, cost: 0.01 },
-        { date: '2026-04-30', tokens: 50, cache: 5, sessions: 1, cost: 0.0023 },
+        { date: '2026-04-30', input_tokens: 30, output_tokens: 20, cache_read_tokens: 5, cache_write_tokens: 1, sessions: 1, errors: 0, cost: 0.0023 },
       ],
     })
 
@@ -44,28 +59,51 @@ describe('usage store analytics adapter', () => {
     expect(store.totalTokens).toBe(150)
     expect(store.cacheHitRate).toBeCloseTo(25 / 125 * 100)
     expect(store.hasData).toBe(true)
-    expect(store.modelUsage).toEqual([
+    expect(store.modelUsage).toHaveLength(2)
-      { model: 'gpt-5', totalTokens: 120, inputTokens: 80, outputTokens: 40, cacheTokens: 20, sessions: 1 },
+    expect(store.modelUsage[0]).toMatchObject({
-      { model: 'unknown', totalTokens: 30, inputTokens: 20, outputTokens: 10, cacheTokens: 5, sessions: 1 },
+      model: 'gpt-5',
-    ])
+      totalTokens: 120,
-    expect(store.dailyUsage).toEqual([
+      inputTokens: 80,
-      { date: '2026-04-29', tokens: 100, cache: 20, sessions: 1, cost: 0.01 },
+      outputTokens: 40,
-      { date: '2026-04-30', tokens: 50, cache: 5, sessions: 1, cost: 0.0023 },
+      cacheTokens: 20,
-    ])
+      cacheWriteTokens: 3,
+      visualTokens: 140,
+      sessions: 1,
+    })
+    expect(store.modelUsage[0].color).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(store.modelUsage[0].inputPercent).toBeCloseTo(80 / 140 * 100)
+    expect(store.modelUsage[0].outputPercent).toBeCloseTo(40 / 140 * 100)
+    expect(store.modelUsage[0].cachePercent).toBeCloseTo(20 / 140 * 100)
+    expect(store.modelUsage[1]).toMatchObject({
+      model: 'unknown',
+      totalTokens: 30,
+      inputTokens: 20,
+      outputTokens: 10,
+      cacheTokens: 5,
+      cacheWriteTokens: 2,
+      visualTokens: 35,
+      sessions: 1,
+    })
+    expect(store.modelUsage[1].color).toBe(store.getModelColor('unknown'))
+    expect(store.modelLegend.map(m => m.model)).toEqual(['gpt-5', 'unknown'])
+    expect(store.dailyUsage).toHaveLength(2)
+    expect(store.dailyUsage[0]).toMatchObject({
+      date: '2026-04-29',
+      input_tokens: 80,
+      output_tokens: 20,
+      cache_read_tokens: 40,
+      cache_write_tokens: 4,
+      visualTokens: 140,
+      sessions: 1,
+      cost: 0.01,
+    })
+    expect(store.dailyUsage[0].inputPercent).toBeCloseTo(80 / 140 * 100)
+    expect(store.dailyUsage[0].outputPercent).toBeCloseTo(20 / 140 * 100)
+    expect(store.dailyUsage[0].cachePercent).toBeCloseTo(40 / 140 * 100)
   })
 
   it('allows callers to request a different period', async () => {
-    usageApiMock.fetchUsageStats.mockResolvedValue({
+    usageApiMock.fetchUsageStats.mockResolvedValue(emptyStats())
-      total_input_tokens: 0,
-      total_output_tokens: 0,
-      total_cache_read_tokens: 0,
-      total_cache_write_tokens: 0,
-      total_reasoning_tokens: 0,
-      total_cost: 0,
-      total_sessions: 0,
-      model_usage: [],
-      daily_usage: [],
-    })
 
     const { useUsageStore } = await import('@/stores/hermes/usage')
     const store = useUsageStore()
@@ -74,4 +112,58 @@ describe('usage store analytics adapter', () => {
     expect(usageApiMock.fetchUsageStats).toHaveBeenCalledWith(7)
     expect(store.hasData).toBe(false)
   })
+
+  it('keeps loading true when an older overlapping request resolves first', async () => {
+    let resolve30: (value: ReturnType<typeof emptyStats>) => void = () => {}
+    let resolve7: (value: ReturnType<typeof emptyStats>) => void = () => {}
+    usageApiMock.fetchUsageStats.mockImplementation((days: number) => new Promise(resolve => {
+      if (days === 30) resolve30 = resolve
+      if (days === 7) resolve7 = resolve
+    }))
+
+    const { useUsageStore } = await import('@/stores/hermes/usage')
+    const store = useUsageStore()
+    const firstLoad = store.loadSessions(30)
+    const secondLoad = store.loadSessions(7)
+
+    expect(store.isLoading).toBe(true)
+    resolve30(emptyStats(30, 30))
+    await firstLoad
+
+    expect(store.isLoading).toBe(true)
+    expect(store.stats).toBeNull()
+
+    resolve7(emptyStats(7, 7))
+    await secondLoad
+
+    expect(store.isLoading).toBe(false)
+    expect(store.stats?.period_days).toBe(7)
+    expect(store.totalSessions).toBe(7)
+  })
+
+  it('ignores stale overlapping responses that resolve after the selected period', async () => {
+    let resolve30: (value: ReturnType<typeof emptyStats>) => void = () => {}
+    let resolve7: (value: ReturnType<typeof emptyStats>) => void = () => {}
+    usageApiMock.fetchUsageStats.mockImplementation((days: number) => new Promise(resolve => {
+      if (days === 30) resolve30 = resolve
+      if (days === 7) resolve7 = resolve
+    }))
+
+    const { useUsageStore } = await import('@/stores/hermes/usage')
+    const store = useUsageStore()
+    const firstLoad = store.loadSessions(30)
+    const secondLoad = store.loadSessions(7)
+
+    resolve7(emptyStats(7, 7))
+    await secondLoad
+
+    expect(store.isLoading).toBe(false)
+    expect(store.stats?.period_days).toBe(7)
+
+    resolve30(emptyStats(30, 30))
+    await firstLoad
+
+    expect(store.stats?.period_days).toBe(7)
+    expect(store.totalSessions).toBe(7)
+  })
 })

tests/client/usage-view-period.test.ts

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent } from 'vue'
+import { mount } from '@vue/test-utils'
+
+const mockUsageStore = vi.hoisted(() => ({
+  isLoading: false,
+  hasData: true,
+  loadSessions: vi.fn(),
+}))
+
+vi.mock('@/stores/hermes/usage', () => ({
+  useUsageStore: () => mockUsageStore,
+}))
+
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({
+    t: (key: string) => key,
+  }),
+}))
+
+vi.mock('naive-ui', () => ({
+  NButton: defineComponent({
+    name: 'NButton',
+    props: {
+      loading: Boolean,
+      type: String,
+      secondary: Boolean,
+      quaternary: Boolean,
+      size: String,
+      ariaPressed: [Boolean, String],
+    },
+    emits: ['click'],
+    template: '<button class="n-button-stub" :data-type="type" :aria-pressed="ariaPressed" @click="$emit(\'click\')"><slot /></button>',
+  }),
+}))
+
+vi.mock('@/components/hermes/usage/StatCards.vue', () => ({
+  default: defineComponent({ name: 'StatCards', template: '<section class="stat-cards-stub" />' }),
+}))
+
+vi.mock('@/components/hermes/usage/ModelBreakdown.vue', () => ({
+  default: defineComponent({ name: 'ModelBreakdown', template: '<section class="model-breakdown-stub" />' }),
+}))
+
+vi.mock('@/components/hermes/usage/DailyTrend.vue', () => ({
+  default: defineComponent({ name: 'DailyTrend', template: '<section class="daily-trend-stub" />' }),
+}))
+
+import UsageView from '@/views/hermes/UsageView.vue'
+
+describe('UsageView period selector', () => {
+  beforeEach(() => {
+    mockUsageStore.isLoading = false
+    mockUsageStore.hasData = true
+    mockUsageStore.loadSessions.mockReset()
+  })
+
+  it('loads the default 30-day period on mount', () => {
+    mount(UsageView)
+
+    expect(mockUsageStore.loadSessions).toHaveBeenCalledWith(30)
+  })
+
+  it('lets users switch usage statistics between common dashboard periods', async () => {
+    const wrapper = mount(UsageView)
+
+    const periodButtons = wrapper.findAll('.period-option')
+    expect(periodButtons.map(button => button.text())).toEqual(['7d', '30d', '90d', '365d'])
+    expect(wrapper.find('.period-selector').attributes('role')).toBe('group')
+
+    await periodButtons[0].trigger('click')
+    expect(mockUsageStore.loadSessions).toHaveBeenLastCalledWith(7)
+    expect(periodButtons[0].attributes('data-type')).toBe('primary')
+    expect(periodButtons[0].attributes('aria-pressed')).toBe('true')
+
+    await wrapper.find('.refresh-button').trigger('click')
+    expect(mockUsageStore.loadSessions).toHaveBeenLastCalledWith(7)
+  })
+})

tests/server/sessions-controller.test.ts

@@ -220,6 +220,43 @@ describe('session conversations controller', () => {
     })
   })
 
+  it('keeps blank model usage under an unknown bucket', async () => {
+    getLocalUsageStatsMock.mockReturnValue({
+      input_tokens: 3,
+      output_tokens: 1,
+      cache_read_tokens: 2,
+      cache_write_tokens: 0,
+      reasoning_tokens: 0,
+      sessions: 1,
+      by_model: [
+        { model: '', input_tokens: 3, output_tokens: 1, cache_read_tokens: 2, cache_write_tokens: 0, reasoning_tokens: 0, sessions: 1 },
+      ],
+      by_day: [],
+    })
+    getUsageStatsFromDbMock.mockResolvedValue({
+      input_tokens: 2,
+      output_tokens: 1,
+      cache_read_tokens: 1,
+      cache_write_tokens: 1,
+      reasoning_tokens: 0,
+      sessions: 1,
+      cost: 0,
+      total_api_calls: 0,
+      by_model: [
+        { model: ' ', input_tokens: 2, output_tokens: 1, cache_read_tokens: 1, cache_write_tokens: 1, reasoning_tokens: 0, sessions: 1 },
+      ],
+      by_day: [],
+    })
+
+    const mod = await import('../../packages/server/src/controllers/hermes/sessions')
+    const ctx: any = { query: { days: '2' }, body: null }
+    await mod.usageStats(ctx)
+
+    expect(ctx.body.model_usage).toEqual([
+      { model: 'unknown', input_tokens: 5, output_tokens: 2, cache_read_tokens: 3, cache_write_tokens: 1, reasoning_tokens: 0, sessions: 2 },
+    ])
+  })
+
   describe('exportSession', () => {
     it('returns session as JSON download with correct headers (full mode)', async () => {
       const sessionData = { id: 'abc-123', title: 'Test Session', messages: [{ id: 1, role: 'user', content: 'hello' }] }