From a85c389610b7b0fbfa9b521e890061a201ff4f2e Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Tue, 29 Sep 2026 20:56:51 +0800
Subject: [PATCH 1/8] record usage costs and support model pricing estimates

---
 docs/harness/usage-cost.md                    |  28 ++
 docs/openapi.json                             | 242 ++++++++++++++++++
 packages/client/src/api/studio/sessions.ts    |   2 +
 .../components/hermes/usage/DailyTrend.vue    |  14 +-
 .../src/components/hermes/usage/StatCards.vue |  13 +-
 .../components/hermes/usage/UsagePricing.vue  |  76 ++++++
 packages/client/src/i18n/locales/ar.ts        |  18 ++
 packages/client/src/i18n/locales/de.ts        |  18 ++
 packages/client/src/i18n/locales/en.ts        |  18 ++
 packages/client/src/i18n/locales/es.ts        |  18 ++
 packages/client/src/i18n/locales/fr.ts        |  18 ++
 packages/client/src/i18n/locales/ja.ts        |  18 ++
 packages/client/src/i18n/locales/ko.ts        |  18 ++
 packages/client/src/i18n/locales/pt.ts        |  18 ++
 packages/client/src/i18n/locales/ru.ts        |  18 ++
 packages/client/src/i18n/locales/zh-TW.ts     |  18 ++
 packages/client/src/i18n/locales/zh.ts        |  18 ++
 packages/client/src/stores/hermes/usage.ts    |   1 +
 packages/client/src/utils/usage-cost.ts       |  17 ++
 .../client/src/views/hermes/UsageView.vue     |   2 +
 packages/ekko-agent/docs/API.md               |  12 +-
 .../ekko-agent/src/model/providers/gemini.ts  |   6 +-
 .../src/model/providers/openai-compatible.ts  |   2 +
 .../src/model/providers/openai-responses.ts   |   2 +
 packages/ekko-agent/src/model/types.ts        |   3 +
 packages/ekko-agent/src/runtime/events.ts     |   2 +
 packages/ekko-agent/src/runtime/runtime.ts    |   9 +
 .../protocol/adapters/responses-stream.ts     |   1 +
 .../protocol/adapters/responses.ts            |   2 +
 .../services/runtime/native-usage.ts          |  38 ++-
 .../services/runtime/run-manager.ts           |   5 +-
 .../hermes/services/history/sessions-db.ts    |  26 +-
 .../modules/studio/contracts/runs/usage.ts    |   8 +
 .../modules/studio/controllers/sessions.ts    |  35 ++-
 .../studio/infrastructure/database/schemas.ts |   9 +
 .../server/src/modules/studio/public/usage.ts |   1 +
 .../repositories/usage-pricing-store.ts       |  20 ++
 .../studio/repositories/usage-store.ts        |  50 +++-
 .../src/modules/studio/routes/sessions.ts     |   2 +
 .../chat-run/handle-ekko-agent-run.ts         |   2 +
 .../services/usage/hermes-cost-fallback.ts    |  31 +++
 .../studio/services/usage/usage-cost.ts       |  70 +++++
 .../studio/services/usage/usage-pricing.ts    |  24 ++
 .../studio/services/usage/usage-recorder.ts   |  14 +
 scripts/generate-openapi.mjs                  |  14 +
 tests/client/usage-cost.test.ts               |  19 ++
 tests/client/usage-view-period.test.ts        |   4 +
 tests/e2e/usage-cost.spec.ts                  |  40 +++
 tests/ekko-agent/model-request.test.ts        |  13 +
 tests/ekko-agent/runtime.test.ts              |   3 +
 tests/server/native-agent-usage.test.ts       |  10 +-
 tests/server/sessions-controller.test.ts      |   5 +-
 tests/server/sessions-routes.test.ts          |   2 +
 tests/server/usage-analytics-db.test.ts       |  17 ++
 tests/server/usage-cost.test.ts               | 116 +++++++++
 .../server/usage-store-agent-stats-db.test.ts |   2 +
 tests/server/usage-store.test.ts              |   7 +-
 57 files changed, 1181 insertions(+), 38 deletions(-)
 create mode 100644 docs/harness/usage-cost.md
 create mode 100644 packages/client/src/components/hermes/usage/UsagePricing.vue
 create mode 100644 packages/client/src/utils/usage-cost.ts
 create mode 100644 packages/server/src/modules/studio/repositories/usage-pricing-store.ts
 create mode 100644 packages/server/src/modules/studio/services/usage/hermes-cost-fallback.ts
 create mode 100644 packages/server/src/modules/studio/services/usage/usage-cost.ts
 create mode 100644 packages/server/src/modules/studio/services/usage/usage-pricing.ts
 create mode 100644 tests/client/usage-cost.test.ts
 create mode 100644 tests/e2e/usage-cost.spec.ts
 create mode 100644 tests/server/usage-cost.test.ts

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
new file mode 100644
index 0000000000..1529351c27
--- /dev/null
+++ b/docs/harness/usage-cost.md
@@ -0,0 +1,28 @@
+# Usage cost accounting
+
+`session_usage` stores nullable `cost_usd` and `cost_source` (`reported`,
+`estimated`, or `unknown`) alongside each deduplicated call/run. Missing costs
+stay NULL, including pre-migration rows. Explicit provider USD zero is known
+free usage; zero from an unpriced native CLI catalog is not proof of free usage.
+
+Studio keeps `total_cost` and daily `cost` numeric for older clients. New
+`cost_coverage` counts reported, estimated and unknown records. Clients show
+"Not recorded" for wholly unknown usage and label partial totals. Empty days
+still show zero. A provider report is not a reconciled account invoice.
+
+The Usage page's Model pricing dialog stores Profile-scoped USD prices per
+million ordinary input, output, cache read and cache write tokens. Provider and
+model IDs must match exactly; no cross-provider model-name fallback is used.
+Native runs without provider metadata use `global`. Missing cache rates leave
+cached usage unpriced. Reasoning is already included in output tokens. Reported
+cost wins over configured rates. Prices apply at recording time, so price edits
+do not reprice historical rows or duplicate run IDs.
+
+Hermes token deduplication and cost recovery are separate. A native session bill
+can supplement a local session only if all its local rows are unpriced and the
+whole session falls inside the period. It cannot be added to a partly priced
+session. Native aggregate costs retain Hermes's session-start date; for sessions
+spanning days, daily coverage stays unknown where charges cannot be attributed.
+
+Validation: `usage-cost.test.ts`, `usage-analytics-db.test.ts`, native usage and
+model adapter tests, and `tests/e2e/usage-cost.spec.ts` cover accounting and UI.
diff --git a/docs/openapi.json b/docs/openapi.json
index f10ae038ca..7a17268b94 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -23117,6 +23117,248 @@
         "x-session-share-permission": "upload"
       }
     },
+    "/api/studio/usage/pricing": {
+      "get": {
+        "tags": [
+          "Sessions"
+        ],
+        "summary": "Get pricing",
+        "description": "Profile-scoped model pricing in USD per million tokens. Exact provider/model match. Applies only to future calls without reported cost; never reprices historical usage.",
+        "operationId": "usagePricing",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Saved pricing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "rates"
+                  ],
+                  "properties": {
+                    "rates": {
+                      "type": "array",
+                      "maxItems": 200,
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "provider",
+                          "model",
+                          "input",
+                          "output"
+                        ],
+                        "properties": {
+                          "provider": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 200
+                          },
+                          "model": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 300
+                          },
+                          "input": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens"
+                          },
+                          "output": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens"
+                          },
+                          "cacheRead": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens",
+                            "nullable": true
+                          },
+                          "cacheWrite": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens",
+                            "nullable": true
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "description": "Not found"
+          }
+        }
+      },
+      "put": {
+        "tags": [
+          "Sessions"
+        ],
+        "summary": "Update pricing",
+        "description": "Profile-scoped model pricing in USD per million tokens. Exact provider/model match. Applies only to future calls without reported cost; never reprices historical usage.",
+        "operationId": "updateUsagePricing",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Saved pricing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "rates"
+                  ],
+                  "properties": {
+                    "rates": {
+                      "type": "array",
+                      "maxItems": 200,
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "provider",
+                          "model",
+                          "input",
+                          "output"
+                        ],
+                        "properties": {
+                          "provider": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 200
+                          },
+                          "model": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 300
+                          },
+                          "input": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens"
+                          },
+                          "output": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens"
+                          },
+                          "cacheRead": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens",
+                            "nullable": true
+                          },
+                          "cacheWrite": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1000000,
+                            "description": "USD per million tokens",
+                            "nullable": true
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or duplicate provider/model pricing"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "rates"
+                ],
+                "properties": {
+                  "rates": {
+                    "type": "array",
+                    "maxItems": 200,
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "provider",
+                        "model",
+                        "input",
+                        "output"
+                      ],
+                      "properties": {
+                        "provider": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 200
+                        },
+                        "model": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 300
+                        },
+                        "input": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1000000,
+                          "description": "USD per million tokens"
+                        },
+                        "output": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1000000,
+                          "description": "USD per million tokens"
+                        },
+                        "cacheRead": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1000000,
+                          "description": "USD per million tokens",
+                          "nullable": true
+                        },
+                        "cacheWrite": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1000000,
+                          "description": "USD per million tokens",
+                          "nullable": true
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/studio/usage/stats": {
       "get": {
         "tags": [
diff --git a/packages/client/src/api/studio/sessions.ts b/packages/client/src/api/studio/sessions.ts
index 7c4f0f28f8..435213132b 100644
--- a/packages/client/src/api/studio/sessions.ts
+++ b/packages/client/src/api/studio/sessions.ts
@@ -628,6 +628,7 @@ export async function exportSession(id: string, mode: 'full' | 'compressed' = 'f
 }
 
 export interface UsageStatsResponse {
+  cost_coverage?: import('@/utils/usage-cost').UsageCostCoverage
   total_input_tokens: number
   total_output_tokens: number
   total_cache_read_tokens: number
@@ -664,6 +665,7 @@ export interface UsageStatsResponse {
     sessions: number
     errors: number
     cost: number
+    cost_coverage?: import('@/utils/usage-cost').UsageCostCoverage
   }>
 }
 
diff --git a/packages/client/src/components/hermes/usage/DailyTrend.vue b/packages/client/src/components/hermes/usage/DailyTrend.vue
index 268d1e71a9..8fd3e98592 100644
--- a/packages/client/src/components/hermes/usage/DailyTrend.vue
+++ b/packages/client/src/components/hermes/usage/DailyTrend.vue
@@ -2,6 +2,7 @@
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useUsageStore } from '@/stores/hermes/usage'
+import { formatUsageCost, usageCostState, type UsageCostCoverage } from '@/utils/usage-cost'
 
 const { t } = useI18n()
 const usageStore = useUsageStore()
@@ -12,10 +13,11 @@ function formatTokens(n: number): string {
   return String(n)
 }
 
-function formatCost(n: number): string {
-  if (n === 0) return '$0.00'
-  if (n < 0.01) return '<$0.01'
-  return '$' + n.toFixed(2)
+function formatCost(day: { cost: number; cost_coverage?: UsageCostCoverage; sessions: number }): string {
+  const amount = formatUsageCost(day.cost, day.cost_coverage, day.sessions > 0)
+  if (amount === null) return t('usage.costStates.unknown')
+  const state = usageCostState(day.cost, day.cost_coverage, day.sessions > 0)
+  return state ? `${amount} · ${t(`usage.costStates.${state}`)}` : amount
 }
 
 function cacheHitRate(d: { input_tokens: number; cache_read_tokens: number }): string {
@@ -69,7 +71,7 @@ const maxTokens = computed(() =>
           <div class="tooltip-row">{{ t('usage.cacheWrite') }}: {{ formatTokens(d.cache_write_tokens) }}</div>
           <div class="tooltip-row">{{ t('usage.cacheHitRate') }}: {{ cacheHitRate(d) }}</div>
           <div class="tooltip-row">{{ t('usage.sessions') }}: {{ d.sessions }}</div>
-          <div class="tooltip-row">{{ t('usage.cost') }}: {{ formatCost(d.cost) }}</div>
+          <div class="tooltip-row">{{ t('usage.cost') }}: {{ formatCost(d) }}</div>
         </div>
       </div>
     </div>
@@ -107,7 +109,7 @@ const maxTokens = computed(() =>
             <td>{{ formatTokens(d.cache_write_tokens) }}</td>
             <td>{{ cacheHitRate(d) }}</td>
             <td>{{ d.sessions }}</td>
-            <td>{{ formatCost(d.cost) }}</td>
+            <td>{{ formatCost(d) }}</td>
           </tr>
         </tbody>
       </table>
diff --git a/packages/client/src/components/hermes/usage/StatCards.vue b/packages/client/src/components/hermes/usage/StatCards.vue
index f200957f2c..bbae819bdb 100644
--- a/packages/client/src/components/hermes/usage/StatCards.vue
+++ b/packages/client/src/components/hermes/usage/StatCards.vue
@@ -1,9 +1,12 @@
 <script setup lang="ts">
 import { useI18n } from 'vue-i18n'
 import { useUsageStore } from '@/stores/hermes/usage'
+import { computed } from 'vue'
+import { formatUsageCost, usageCostState } from '@/utils/usage-cost'
 
 const { t } = useI18n()
 const usageStore = useUsageStore()
+const costState = computed(() => usageCostState(usageStore.estimatedCost, usageStore.stats?.cost_coverage, usageStore.hasData))
 
 function formatTokens(n: number): string {
   if (n >= 1000000) return (n / 1000000).toFixed(1) + 'M'
@@ -11,11 +14,6 @@ function formatTokens(n: number): string {
   return String(n)
 }
 
-function formatCost(n: number): string {
-  if (n === 0) return '$0.00'
-  if (n < 0.01) return '<$0.01'
-  return '$' + n.toFixed(2)
-}
 </script>
 
 <template>
@@ -34,8 +32,9 @@ function formatCost(n: number): string {
       <div class="stat-sub">{{ t('usage.avgPerDay', { n: usageStore.avgSessionsPerDay.toFixed(1) }) }}</div>
     </div>
     <div class="stat-card">
-      <div class="stat-label">{{ t('usage.estimatedCost') }}</div>
-      <div class="stat-value">{{ formatCost(usageStore.estimatedCost) }}</div>
+      <div class="stat-label">{{ t('usage.cost') }} (USD)</div>
+      <div class="stat-value">{{ formatUsageCost(usageStore.estimatedCost, usageStore.stats?.cost_coverage, usageStore.hasData) ?? t('usage.costStates.unknown') }}</div>
+      <div v-if="costState && costState !== 'unknown'" class="stat-sub">{{ t(`usage.costStates.${costState}`) }}</div>
     </div>
     <div class="stat-card">
       <div class="stat-label">{{ t('usage.cacheHitRate') }}</div>
diff --git a/packages/client/src/components/hermes/usage/UsagePricing.vue b/packages/client/src/components/hermes/usage/UsagePricing.vue
new file mode 100644
index 0000000000..e941b83f8a
--- /dev/null
+++ b/packages/client/src/components/hermes/usage/UsagePricing.vue
@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { NAlert, NButton, NInput, NInputNumber, NModal } from 'naive-ui'
+import { useI18n } from 'vue-i18n'
+import { request } from '@/api/client'
+
+interface Rate {
+  provider: string
+  model: string
+  input: number | null
+  output: number | null
+  cacheRead?: number | null
+  cacheWrite?: number | null
+}
+const { t } = useI18n()
+const show = ref(false)
+const busy = ref(false)
+const error = ref(false)
+const rates = ref<Rate[]>([])
+const fields = ['input', 'output', 'cacheRead', 'cacheWrite'] as const
+
+async function open() {
+  busy.value = true
+  error.value = false
+  try {
+    rates.value = (await request<{ rates: Rate[] }>('/api/studio/usage/pricing')).rates
+    show.value = true
+  } catch {
+    error.value = true
+  } finally { busy.value = false }
+}
+
+async function save() {
+  error.value = false
+  busy.value = true
+  try {
+    await request('/api/studio/usage/pricing', { method: 'PUT', body: JSON.stringify({ rates: rates.value }) })
+    show.value = false
+  } catch {
+    error.value = true
+  } finally { busy.value = false }
+}
+</script>
+
+<template>
+  <NButton size="small" quaternary :loading="busy && !show" @click="open">{{ t('usage.pricing.title') }}</NButton>
+  <span v-if="error && !show" role="alert">{{ t('usage.pricing.error') }}</span>
+  <NModal v-model:show="show" preset="card" :title="t('usage.pricing.title')" class="usage-pricing" style="width: min(920px, 94vw)" :mask-closable="!busy" :closable="!busy">
+    <p class="pricing-help">{{ t('usage.pricing.help') }}</p>
+    <NAlert v-if="error" type="error" class="pricing-error">{{ t('usage.pricing.error') }}</NAlert>
+    <div class="pricing-rows">
+      <div v-for="(rate, index) in rates" :key="index" class="pricing-row">
+        <label>{{ t('usage.pricing.provider') }}<NInput v-model:value="rate.provider" :disabled="busy" :input-props="{ 'aria-label': t('usage.pricing.provider') }" placeholder="global" /></label>
+        <label>{{ t('usage.pricing.model') }}<NInput v-model:value="rate.model" :disabled="busy" :input-props="{ 'aria-label': t('usage.pricing.model') }" placeholder="model-id" /></label>
+        <label v-for="field in fields" :key="field">{{ t(`usage.pricing.${field}`) }}<NInputNumber v-model:value="rate[field]" :disabled="busy" :input-props="{ 'aria-label': t(`usage.pricing.${field}`) }" :min="0" :max="1000000" :show-button="false" :placeholder="t('usage.costStates.unknown')" /></label>
+        <NButton :disabled="busy" @click="rates.splice(index, 1)">{{ t('common.delete') }}</NButton>
+      </div>
+    </div>
+    <template #footer>
+      <div class="pricing-actions">
+        <NButton :disabled="busy || rates.length >= 200" @click="rates.push({ provider: 'global', model: '', input: null, output: null })">{{ t('common.add') }}</NButton>
+        <NButton type="primary" :loading="busy" @click="save">{{ t('common.save') }}</NButton>
+      </div>
+    </template>
+  </NModal>
+</template>
+
+<style scoped lang="scss">
+.pricing-help { margin: 0 0 16px; line-height: 1.6; }
+.pricing-error { margin-bottom: 12px; }
+.pricing-rows { max-height: 60vh; overflow: auto; }
+.pricing-row { display: grid; grid-template-columns: repeat(2, minmax(110px, 1.5fr)) repeat(4, minmax(85px, 1fr)) auto; align-items: end; gap: 10px; margin-bottom: 14px; }
+.pricing-row label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; }
+.pricing-actions { display: flex; justify-content: space-between; }
+@media (max-width: 800px) { .pricing-row { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+</style>
diff --git a/packages/client/src/i18n/locales/ar.ts b/packages/client/src/i18n/locales/ar.ts
index 67f138f4dd..e7013b78e3 100644
--- a/packages/client/src/i18n/locales/ar.ts
+++ b/packages/client/src/i18n/locales/ar.ts
@@ -3532,6 +3532,24 @@ export default {
 
   // Usage
   usage: {
+    costStates: {
+      unknown: "غير مسجل",
+      partial: "تكلفة جزئية؛ بعض الاستخدام بلا تسعير",
+      reported: "التكلفة الواردة من المزود",
+      estimated: "تكلفة تقديرية",
+      mixed: "تشمل تكاليف واردة وتقديرية",
+    },
+    pricing: {
+      title: "أسعار النماذج",
+      help: "دولار لكل مليون رمز. يجب تطابق معرفَي المزود والنموذج تمامًا (مثل global). يُستخدم التقدير عند غياب التكلفة فقط. سعر التخزين المؤقت الفارغ يعني أنه غير معروف. تسري التغييرات على الاستدعاءات القادمة دون إعادة حساب السجل.",
+      provider: "معرف المزود",
+      model: "معرف النموذج",
+      input: "الإدخال",
+      output: "الإخراج",
+      cacheRead: "قراءة التخزين المؤقت",
+      cacheWrite: "كتابة التخزين المؤقت",
+      error: "تعذر تحميل الأسعار أو حفظها. تحقق من المعرفات والتكرارات وأن الأسعار غير سالبة.",
+    },
     title: 'إحصائيات الاستخدام',
     refresh: 'تحديث',
     totalTokens: 'إجمالي التوكنات',
diff --git a/packages/client/src/i18n/locales/de.ts b/packages/client/src/i18n/locales/de.ts
index e3672776d1..e4bb509db4 100644
--- a/packages/client/src/i18n/locales/de.ts
+++ b/packages/client/src/i18n/locales/de.ts
@@ -2808,6 +2808,24 @@ jobTriggered: 'Job ausgelost',
 
   // Usage
   usage: {
+    costStates: {
+      unknown: "Nicht erfasst",
+      partial: "Teilkosten; einige Nutzungen ohne Preis",
+      reported: "Vom Anbieter gemeldete Kosten",
+      estimated: "Geschätzte Kosten",
+      mixed: "Gemeldete und geschätzte Kosten",
+    },
+    pricing: {
+      title: "Modellpreise",
+      help: "USD pro Million Tokens. Anbieter- und Modell-ID müssen genau passen (z. B. global). Schätzung nur ohne gemeldete Kosten. Leere Cachepreise bedeuten unbekannt. Änderungen gelten für künftige Aufrufe; frühere Kosten werden nicht neu berechnet.",
+      provider: "Anbieter-ID",
+      model: "Modell-ID",
+      input: "Eingabe",
+      output: "Ausgabe",
+      cacheRead: "Cache lesen",
+      cacheWrite: "Cache schreiben",
+      error: "Preise konnten nicht geladen oder gespeichert werden. IDs, Duplikate und nicht negative Preise prüfen.",
+    },
     title: 'Nutzungsstatistiken',
     refresh: 'Aktualisieren',
     totalTokens: 'Gesamt-Tokens',
diff --git a/packages/client/src/i18n/locales/en.ts b/packages/client/src/i18n/locales/en.ts
index 1313e611a5..6c24fbfc47 100644
--- a/packages/client/src/i18n/locales/en.ts
+++ b/packages/client/src/i18n/locales/en.ts
@@ -3551,6 +3551,24 @@ export default {
 
   // Usage
   usage: {
+    costStates: {
+      unknown: "Not recorded",
+      partial: "Partial cost; some usage is unpriced",
+      reported: "Provider-reported cost",
+      estimated: "Estimated cost",
+      mixed: "Includes reported and estimated costs",
+    },
+    pricing: {
+      title: "Model pricing",
+      help: "USD per million tokens. Match provider and model IDs exactly (e.g. global). Used only when no cost is returned. Blank cache rates mean unknown. Changes apply to future calls; historical costs are not recalculated.",
+      provider: "Provider ID",
+      model: "Model ID",
+      input: "Input",
+      output: "Output",
+      cacheRead: "Cache read",
+      cacheWrite: "Cache write",
+      error: "Could not load or save pricing. Check provider/model IDs, duplicates and non-negative rates.",
+    },
     title: 'Usage Statistics',
     refresh: 'Refresh',
     totalTokens: 'Total Tokens',
diff --git a/packages/client/src/i18n/locales/es.ts b/packages/client/src/i18n/locales/es.ts
index af75da05f6..5c7176c1a7 100644
--- a/packages/client/src/i18n/locales/es.ts
+++ b/packages/client/src/i18n/locales/es.ts
@@ -2808,6 +2808,24 @@ jobTriggered: 'Job ejecutado',
 
   // Usage
   usage: {
+    costStates: {
+      unknown: "Sin registrar",
+      partial: "Coste parcial; falta valorar parte del uso",
+      reported: "Coste informado por el proveedor",
+      estimated: "Coste estimado",
+      mixed: "Incluye costes informados y estimados",
+    },
+    pricing: {
+      title: "Precios de modelos",
+      help: "USD por millón de tokens. Coincidencia exacta de ID de proveedor y modelo (p. ej. global). Solo se estima si no se recibe un coste. Caché sin precio significa desconocido. Cambios para futuras llamadas, sin recalcular el historial.",
+      provider: "ID del proveedor",
+      model: "ID del modelo",
+      input: "Entrada",
+      output: "Salida",
+      cacheRead: "Lectura de caché",
+      cacheWrite: "Escritura de caché",
+      error: "No se pudieron cargar o guardar los precios. Revise los ID, duplicados y precios no negativos.",
+    },
     title: 'Estadisticas de uso',
     refresh: 'Actualizar',
     totalTokens: 'Total de tokens',
diff --git a/packages/client/src/i18n/locales/fr.ts b/packages/client/src/i18n/locales/fr.ts
index 8a77ca4c2e..94e5bf861d 100644
--- a/packages/client/src/i18n/locales/fr.ts
+++ b/packages/client/src/i18n/locales/fr.ts
@@ -2808,6 +2808,24 @@ jobTriggered: 'Job declenche',
 
   // Usage
   usage: {
+    costStates: {
+      unknown: "Non enregistré",
+      partial: "Coût partiel ; certaines utilisations sans tarif",
+      reported: "Coût indiqué par le fournisseur",
+      estimated: "Coût estimé",
+      mixed: "Coûts indiqués et estimés",
+    },
+    pricing: {
+      title: "Tarifs des modèles",
+      help: "USD par million de tokens. Identifiants fournisseur et modèle exacts (par ex. global). Estimation uniquement si aucun coût reçu. Cache sans tarif : coût inconnu. Modifications pour les prochains appels, sans recalcul du passé.",
+      provider: "ID fournisseur",
+      model: "ID modèle",
+      input: "Entrée",
+      output: "Sortie",
+      cacheRead: "Lecture du cache",
+      cacheWrite: "Écriture du cache",
+      error: "Échec du chargement ou de la sauvegarde. Vérifiez les ID, les doublons et les tarifs non négatifs.",
+    },
     title: 'Statistiques d\'utilisation',
     refresh: 'Actualiser',
     totalTokens: 'Total des jetons',
diff --git a/packages/client/src/i18n/locales/ja.ts b/packages/client/src/i18n/locales/ja.ts
index f70bc0113e..561fb95e0f 100644
--- a/packages/client/src/i18n/locales/ja.ts
+++ b/packages/client/src/i18n/locales/ja.ts
@@ -2807,6 +2807,24 @@ export default {
 
   // 使用統計
   usage: {
+    costStates: {
+      unknown: "未記録",
+      partial: "一部の費用のみ記録",
+      reported: "プロバイダー報告額",
+      estimated: "推定費用",
+      mixed: "報告額と推定額を含む",
+    },
+    pricing: {
+      title: "モデル料金",
+      help: "100万トークンあたりの米ドル。プロバイダーとモデルの ID を完全一致で指定（例: global）。費用が返されない場合のみ推定します。キャッシュ料金の空欄は不明を意味します。変更は今後の呼び出しに適用され、過去の費用は再計算されません。",
+      provider: "プロバイダー ID",
+      model: "モデル ID",
+      input: "入力",
+      output: "出力",
+      cacheRead: "キャッシュ読取",
+      cacheWrite: "キャッシュ書込",
+      error: "料金の読み込みまたは保存に失敗しました。ID、重複、負の料金がないか確認してください。",
+    },
     title: '使用統計',
     refresh: '更新',
     totalTokens: '総トークン数',
diff --git a/packages/client/src/i18n/locales/ko.ts b/packages/client/src/i18n/locales/ko.ts
index 3273c9a5cd..ead44db086 100644
--- a/packages/client/src/i18n/locales/ko.ts
+++ b/packages/client/src/i18n/locales/ko.ts
@@ -2807,6 +2807,24 @@ export default {
 
   // 사용량
   usage: {
+    costStates: {
+      unknown: "미기록",
+      partial: "일부 비용만 기록됨",
+      reported: "공급자 보고 비용",
+      estimated: "추정 비용",
+      mixed: "보고 비용 및 추정 비용 포함",
+    },
+    pricing: {
+      title: "모델 단가",
+      help: "백만 토큰당 USD입니다. 공급자와 모델 ID를 정확히 일치시키세요(예: global). 비용이 반환되지 않을 때만 추정합니다. 캐시 단가가 비어 있으면 알 수 없음입니다. 이후 호출부터 적용되며 과거 비용은 다시 계산하지 않습니다.",
+      provider: "공급자 ID",
+      model: "모델 ID",
+      input: "입력",
+      output: "출력",
+      cacheRead: "캐시 읽기",
+      cacheWrite: "캐시 쓰기",
+      error: "단가를 불러오거나 저장하지 못했습니다. ID, 중복 및 음수 단가를 확인하세요.",
+    },
     title: '사용량 통계',
     refresh: '새로고침',
     totalTokens: '총 토큰 수',
diff --git a/packages/client/src/i18n/locales/pt.ts b/packages/client/src/i18n/locales/pt.ts
index f6ef6197d0..c537ea636a 100644
--- a/packages/client/src/i18n/locales/pt.ts
+++ b/packages/client/src/i18n/locales/pt.ts
@@ -2808,6 +2808,24 @@ jobTriggered: 'Job acionado',
 
   // Usage
   usage: {
+    costStates: {
+      unknown: "Não registrado",
+      partial: "Custo parcial; parte do uso sem preço",
+      reported: "Custo informado pelo provedor",
+      estimated: "Custo estimado",
+      mixed: "Inclui custos informados e estimados",
+    },
+    pricing: {
+      title: "Preços dos modelos",
+      help: "USD por milhão de tokens. IDs de provedor e modelo devem corresponder exatamente (ex.: global). Estimativa apenas sem custo informado. Cache sem preço significa desconhecido. Alterações valem para futuras chamadas, sem recalcular o histórico.",
+      provider: "ID do provedor",
+      model: "ID do modelo",
+      input: "Entrada",
+      output: "Saída",
+      cacheRead: "Leitura de cache",
+      cacheWrite: "Gravação de cache",
+      error: "Não foi possível carregar ou salvar preços. Verifique IDs, duplicatas e preços não negativos.",
+    },
     title: 'Estatisticas de uso',
     refresh: 'Atualizar',
     totalTokens: 'Total de tokens',
diff --git a/packages/client/src/i18n/locales/ru.ts b/packages/client/src/i18n/locales/ru.ts
index 60509138d4..9e91118cdc 100644
--- a/packages/client/src/i18n/locales/ru.ts
+++ b/packages/client/src/i18n/locales/ru.ts
@@ -3187,6 +3187,24 @@ export default {
 
 
   usage: {
+    costStates: {
+      unknown: "Не записано",
+      partial: "Часть расходов не учтена",
+      reported: "Стоимость от провайдера",
+      estimated: "Оценочная стоимость",
+      mixed: "Включает данные провайдера и оценки",
+    },
+    pricing: {
+      title: "Тарифы моделей",
+      help: "USD за миллион токенов. ID провайдера и модели должны совпадать точно (например global). Оценка применяется, если стоимость не получена. Пустой тариф кеша означает неизвестную стоимость. Изменения действуют для будущих вызовов без пересчёта истории.",
+      provider: "ID провайдера",
+      model: "ID модели",
+      input: "Ввод",
+      output: "Вывод",
+      cacheRead: "Чтение кеша",
+      cacheWrite: "Запись кеша",
+      error: "Не удалось загрузить или сохранить тарифы. Проверьте ID, дубликаты и отсутствие отрицательных цен.",
+    },
     title: 'Статистика использования',
     refresh: 'Обновить',
     totalTokens: 'Всего токенов',
diff --git a/packages/client/src/i18n/locales/zh-TW.ts b/packages/client/src/i18n/locales/zh-TW.ts
index de32330605..44c87f9341 100644
--- a/packages/client/src/i18n/locales/zh-TW.ts
+++ b/packages/client/src/i18n/locales/zh-TW.ts
@@ -3493,6 +3493,24 @@ export default {
 
   // 用量統計
   usage: {
+    costStates: {
+      unknown: "未記錄",
+      partial: "部分費用，其餘未記錄",
+      reported: "上游回傳費用",
+      estimated: "估算費用",
+      mixed: "含上游費用與估算費用",
+    },
+    pricing: {
+      title: "模型單價",
+      help: "單位為美元／百萬 Token。依供應商和模型 ID 精確匹配（例如 global），僅在上游未回傳費用時估算。快取單價留空表示未知。修改從後續呼叫生效，不重算歷史費用。",
+      provider: "供應商 ID",
+      model: "模型 ID",
+      input: "輸入",
+      output: "輸出",
+      cacheRead: "快取讀取",
+      cacheWrite: "快取寫入",
+      error: "無法讀取或儲存單價。請檢查供應商、模型是否填寫或重複，單價必須為非負數。",
+    },
     title: '用量統計',
     refresh: '重新整理',
     totalTokens: '總 Token 數',
diff --git a/packages/client/src/i18n/locales/zh.ts b/packages/client/src/i18n/locales/zh.ts
index 33424a4bdf..0afcb8f832 100644
--- a/packages/client/src/i18n/locales/zh.ts
+++ b/packages/client/src/i18n/locales/zh.ts
@@ -3599,6 +3599,24 @@ export default {
 
   // 用量统计
   usage: {
+    costStates: {
+      unknown: "未记录",
+      partial: "部分费用，其余未记录",
+      reported: "上游返回费用",
+      estimated: "估算费用",
+      mixed: "含上游费用与估算费用",
+    },
+    pricing: {
+      title: "模型单价",
+      help: "单位为美元／百万 Token。按供应商和模型 ID 精确匹配（例如 global），仅在上游未返回费用时估算。缓存单价留空表示未知。修改从后续调用生效，不重算历史费用。",
+      provider: "供应商 ID",
+      model: "模型 ID",
+      input: "输入",
+      output: "输出",
+      cacheRead: "缓存读取",
+      cacheWrite: "缓存写入",
+      error: "无法读取或保存单价。请检查供应商、模型是否填写或重复，单价必须为非负数。",
+    },
     title: '用量统计',
     refresh: '刷新',
     totalTokens: '总 Token 数',
diff --git a/packages/client/src/stores/hermes/usage.ts b/packages/client/src/stores/hermes/usage.ts
index b4b1674e0d..4fe1dd730f 100644
--- a/packages/client/src/stores/hermes/usage.ts
+++ b/packages/client/src/stores/hermes/usage.ts
@@ -3,6 +3,7 @@ import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 
 interface DailyUsage {
+  cost_coverage?: import('@/utils/usage-cost').UsageCostCoverage
   date: string
   input_tokens: number
   output_tokens: number
diff --git a/packages/client/src/utils/usage-cost.ts b/packages/client/src/utils/usage-cost.ts
new file mode 100644
index 0000000000..7d910f4592
--- /dev/null
+++ b/packages/client/src/utils/usage-cost.ts
@@ -0,0 +1,17 @@
+export interface UsageCostCoverage { reported: number; estimated: number; unknown: number }
+export type UsageCostState = 'unknown' | 'partial' | 'reported' | 'estimated' | 'mixed' | ''
+
+export function usageCostState(amount: number, coverage?: UsageCostCoverage, hasActivity = true): UsageCostState {
+  if (!coverage) return amount > 0 || !hasActivity ? '' : 'unknown'
+  const known = coverage.reported + coverage.estimated
+  if (!known) return coverage.unknown > 0 || hasActivity ? 'unknown' : ''
+  if (coverage.unknown > 0) return 'partial'
+  if (!coverage.reported) return 'estimated'
+  return coverage.estimated > 0 ? 'mixed' : 'reported'
+}
+
+export function formatUsageCost(amount: number, coverage?: UsageCostCoverage, hasActivity = true): string | null {
+  if (usageCostState(amount, coverage, hasActivity) === 'unknown') return null
+  if (amount === 0) return '$0.00'
+  return amount < 0.01 ? '<$0.01' : `$${amount.toFixed(2)}`
+}
diff --git a/packages/client/src/views/hermes/UsageView.vue b/packages/client/src/views/hermes/UsageView.vue
index 9769c0899c..07e31ce63e 100644
--- a/packages/client/src/views/hermes/UsageView.vue
+++ b/packages/client/src/views/hermes/UsageView.vue
@@ -8,6 +8,7 @@ import StatCards from '@/components/hermes/usage/StatCards.vue'
 import ModelBreakdown from '@/components/hermes/usage/ModelBreakdown.vue'
 import AgentBreakdown from '@/components/hermes/usage/AgentBreakdown.vue'
 import DailyTrend from '@/components/hermes/usage/DailyTrend.vue'
+import UsagePricing from '@/components/hermes/usage/UsagePricing.vue'
 
 const { t } = useI18n()
 const usageStore = useUsageStore()
@@ -44,6 +45,7 @@ onMounted(() => {
     <header class="page-header">
       <h2 class="header-title">{{ t('usage.title') }}</h2>
       <div class="usage-toolbar">
+        <UsagePricing />
         <div class="period-selector" role="group" aria-label="Usage statistics period">
           <NButton
             v-for="option in periodOptions"
diff --git a/packages/ekko-agent/docs/API.md b/packages/ekko-agent/docs/API.md
index 5c6877d57f..4bff73524f 100644
--- a/packages/ekko-agent/docs/API.md
+++ b/packages/ekko-agent/docs/API.md
@@ -500,6 +500,14 @@ npm run harness:check
 
 `harness:check` 依次检查文档公共面、TypeScript 类型和全部测试。新增、修改或删除公共 API 而未刷新本文档时，`api:docs:check` 会直接失败。
 
+### Usage cost metadata
+
+`ModelUsage.costUsd` carries an optional provider-reported USD amount. Missing
+cost remains unknown; an explicit provider zero remains zero. `costSource` can
+mark an estimate. OpenAI Chat/Responses adapters preserve `usage.cost` when
+provided. `subagent.complete` includes a total only when every child model call
+has a known cost, avoiding partial amounts being presented as complete bills.
+
 <!-- BEGIN GENERATED EKKO PUBLIC API -->
 
 ## Generated public API inventory
@@ -2660,6 +2668,8 @@ export interface AgentToolCall {
 }
 
 export interface ModelUsage {
+  costUsd?: number
+  costSource?: 'reported' | 'estimated'
   inputTokens?: number
   outputTokens?: number
   totalTokens?: number
@@ -2785,7 +2795,7 @@ export class EkkoRecoveryService {
 ### `src/runtime/events.ts`
 
 ```ts
-export type AgentRuntimeEvent = | { type: 'plan.updated'; runId: string; plan: import('../tools/plan').AgentTaskPlan } | { type: 'run.started'; runId: string; maxSteps: number } | { type: 'memory.retrieved'; runId: string; diagnostics: MemoryContextDiagnostics; memoryIds: string[] } | { type: 'skill.review.started'; runId: string; reviewId: string } | { type: 'skill.review.completed'; runId: string; reviewId: string; mutations: number } | { type: 'skill.review.failed'; runId: string; reviewId: string; error: string } | { type: 'model.started'; runId: string; step: number } | { type: 'context.estimated'; runId: string; step: number; estimate: AgentRuntimeContextEstimate } | { type: 'model.retry'; runId: string; step: number; retry: number; maxRetries: number; error: string } | { type: 'model.message'; runId: string; step: number; message: AgentOutputMessage } | { type: 'model.delta'; runId: string; step: number; text: string } | { type: 'model.reasoning'; runId: string; step: number; text: string } | { type: 'model.tool_call'; runId: string; step: number; toolCall: AgentToolCall } | { type: 'model.usage'; runId: string; step: number; usage: ModelUsage } | { type: 'model.context'; runId: string; step: number; context: unknown } | { type: 'tool.started'; runId: string; step: number; toolCallId: string; toolName: string; arguments: Record<string, unknown> } | { type: 'tool.completed'; runId: string; step: number; toolCallId: string; toolName: string; result: AgentToolResult; durationMs: number } | { type: 'tool.failed'; runId: string; step: number; toolCallId: string; toolName: string; result: AgentToolResult; durationMs: number } | { type: 'subagent.start'; runId: string; subagentId: string; goal: string; background: boolean; model?: string; startedAt: number } | { type: 'subagent.text'; runId: string; childRunId?: string; subagentId: string; goal: string; background: boolean; text: string } | { type: 'subagent.thinking'; runId: string; childRunId?: string; subagentId: string; goal: string; background: boolean; text: string } | { type: 'subagent.tool'; runId: string; childRunId?: string; subagentId: string; goal: string; background: boolean; toolName: string; arguments: Record<string, unknown>; toolCount: number } | { type: 'subagent.complete' runId: string childRunId?: string subagentId: string goal: string background: boolean status: 'completed' | 'failed' | 'interrupted' summary: string output: string outputTail: string durationMs: number toolCount: number apiCalls: number inputTokens: number outputTokens: number cacheReadTokens: number cacheWriteTokens: number reasoningTokens: number continuationContext?: EkkoBackgroundContinuationContext } | { type: 'run.tool_recovery_required'; runId: string; toolName: string; failures: number } | { type: 'run.completed'; runId: string; output: AgentOutputMessage; steps: number; context?: unknown; contextEstimate?: AgentRuntimeContextEstimate } | { type: 'run.failed'; runId: string; error: string; steps: number } | { type: 'run.max_steps'; runId: string; maxSteps: number }
+export type AgentRuntimeEvent = | { type: 'plan.updated'; runId: string; plan: import('../tools/plan').AgentTaskPlan } | { type: 'run.started'; runId: string; maxSteps: number } | { type: 'memory.retrieved'; runId: string; diagnostics: MemoryContextDiagnostics; memoryIds: string[] } | { type: 'skill.review.started'; runId: string; reviewId: string } | { type: 'skill.review.completed'; runId: string; reviewId: string; mutations: number } | { type: 'skill.review.failed'; runId: string; reviewId: string; error: string } | { type: 'model.started'; runId: string; step: number } | { type: 'context.estimated'; runId: string; step: number; estimate: AgentRuntimeContextEstimate } | { type: 'model.retry'; runId: string; step: number; retry: number; maxRetries: number; error: string } | { type: 'model.message'; runId: string; step: number; message: AgentOutputMessage } | { type: 'model.delta'; runId: string; step: number; text: string } | { type: 'model.reasoning'; runId: string; step: number; text: string } | { type: 'model.tool_call'; runId: string; step: number; toolCall: AgentToolCall } | { type: 'model.usage'; runId: string; step: number; usage: ModelUsage } | { type: 'model.context'; runId: string; step: number; context: unknown } | { type: 'tool.started'; runId: string; step: number; toolCallId: string; toolName: string; arguments: Record<string, unknown> } | { type: 'tool.completed'; runId: string; step: number; toolCallId: string; toolName: string; result: AgentToolResult; durationMs: number } | { type: 'tool.failed'; runId: string; step: number; toolCallId: string; toolName: string; result: AgentToolResult; durationMs: number } | { type: 'subagent.start'; runId: string; subagentId: string; goal: string; background: boolean; model?: string; startedAt: number } | { type: 'subagent.text'; runId: string; childRunId?: string; subagentId: string; goal: string; background: boolean; text: string } | { type: 'subagent.thinking'; runId: string; childRunId?: string; subagentId: string; goal: string; background: boolean; text: string } | { type: 'subagent.tool'; runId: string; childRunId?: string; subagentId: string; goal: string; background: boolean; toolName: string; arguments: Record<string, unknown>; toolCount: number } | { type: 'subagent.complete' runId: string childRunId?: string subagentId: string goal: string background: boolean status: 'completed' | 'failed' | 'interrupted' summary: string output: string outputTail: string durationMs: number toolCount: number apiCalls: number inputTokens: number outputTokens: number cacheReadTokens: number cacheWriteTokens: number reasoningTokens: number costUsd?: number costSource?: 'reported' | 'estimated' continuationContext?: EkkoBackgroundContinuationContext } | { type: 'run.tool_recovery_required'; runId: string; toolName: string; failures: number } | { type: 'run.completed'; runId: string; output: AgentOutputMessage; steps: number; context?: unknown; contextEstimate?: AgentRuntimeContextEstimate } | { type: 'run.failed'; runId: string; error: string; steps: number } | { type: 'run.max_steps'; runId: string; maxSteps: number }
 ```
 ### `src/runtime/manager.ts`
 
diff --git a/packages/ekko-agent/src/model/providers/gemini.ts b/packages/ekko-agent/src/model/providers/gemini.ts
index 04773f9348..30f9250d68 100644
--- a/packages/ekko-agent/src/model/providers/gemini.ts
+++ b/packages/ekko-agent/src/model/providers/gemini.ts
@@ -238,8 +238,10 @@ function toGeminiTool(tool: AgentToolDefinition): NonNullable<NonNullable<Gemini
 
 function normalizeUsage(usage: NonNullable<GeminiResponse['usageMetadata']>): ModelUsage {
   return {
-    inputTokens: usage.promptTokenCount,
-    outputTokens: usage.candidatesTokenCount,
+    // Gemini promptTokenCount includes cache; thoughts are separate from candidates.
+    // https://ai.google.dev/api/generate-content#UsageMetadata
+    inputTokens: usage.promptTokenCount == null ? undefined : Math.max(0, usage.promptTokenCount - (usage.cachedContentTokenCount ?? 0)),
+    outputTokens: usage.candidatesTokenCount == null ? undefined : usage.candidatesTokenCount + (usage.thoughtsTokenCount ?? 0),
     totalTokens: usage.totalTokenCount,
     cacheReadTokens: usage.cachedContentTokenCount,
     reasoningTokens: usage.thoughtsTokenCount,
diff --git a/packages/ekko-agent/src/model/providers/openai-compatible.ts b/packages/ekko-agent/src/model/providers/openai-compatible.ts
index cd594f5df2..49da363378 100644
--- a/packages/ekko-agent/src/model/providers/openai-compatible.ts
+++ b/packages/ekko-agent/src/model/providers/openai-compatible.ts
@@ -105,6 +105,7 @@ interface OpenAIChatResponse {
     finish_reason?: string | null
   }>
   usage?: {
+    cost?: number
     prompt_tokens?: number
     completion_tokens?: number
     total_tokens?: number
@@ -761,6 +762,7 @@ function normalizeUsage(usage: NonNullable<OpenAIChatResponse['usage']>): ModelU
   const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? 0
   const inputTokens = usage.prompt_tokens ?? 0
   return {
+    ...(typeof usage.cost === 'number' && Number.isFinite(usage.cost) && usage.cost >= 0 ? { costUsd: usage.cost } : {}),
     inputTokens: Math.max(0, inputTokens - cacheReadTokens),
     outputTokens: usage.completion_tokens,
     totalTokens: usage.total_tokens,
diff --git a/packages/ekko-agent/src/model/providers/openai-responses.ts b/packages/ekko-agent/src/model/providers/openai-responses.ts
index 595c0a8b0a..dcb237768c 100644
--- a/packages/ekko-agent/src/model/providers/openai-responses.ts
+++ b/packages/ekko-agent/src/model/providers/openai-responses.ts
@@ -87,6 +87,7 @@ interface OpenAIResponsesResponse {
   reasoning_text?: string
   reasoning_summary?: string
   usage?: {
+    cost?: number
     input_tokens?: number
     output_tokens?: number
     total_tokens?: number
@@ -475,6 +476,7 @@ function normalizeUsage(usage: NonNullable<OpenAIResponsesResponse['usage']>): M
   const cacheReadTokens = usage.input_tokens_details?.cached_tokens ?? 0
   const inputTokens = usage.input_tokens ?? 0
   return {
+    ...(typeof usage.cost === 'number' && Number.isFinite(usage.cost) && usage.cost >= 0 ? { costUsd: usage.cost } : {}),
     inputTokens: Math.max(0, inputTokens - cacheReadTokens),
     outputTokens: usage.output_tokens,
     totalTokens: usage.total_tokens,
diff --git a/packages/ekko-agent/src/model/types.ts b/packages/ekko-agent/src/model/types.ts
index a31b2cc065..af72a63732 100644
--- a/packages/ekko-agent/src/model/types.ts
+++ b/packages/ekko-agent/src/model/types.ts
@@ -61,6 +61,9 @@ export interface AgentToolCall {
 }
 
 export interface ModelUsage {
+  /** Provider-reported USD cost, when supplied. Missing is not free. */
+  costUsd?: number
+  costSource?: 'reported' | 'estimated'
   inputTokens?: number
   outputTokens?: number
   totalTokens?: number
diff --git a/packages/ekko-agent/src/runtime/events.ts b/packages/ekko-agent/src/runtime/events.ts
index 480aa474d0..8c58ef0209 100644
--- a/packages/ekko-agent/src/runtime/events.ts
+++ b/packages/ekko-agent/src/runtime/events.ts
@@ -46,6 +46,8 @@ export type AgentRuntimeEvent =
       cacheReadTokens: number
       cacheWriteTokens: number
       reasoningTokens: number
+      costUsd?: number
+      costSource?: 'reported' | 'estimated'
       continuationContext?: EkkoBackgroundContinuationContext
     }
   | { type: 'run.tool_recovery_required'; runId: string; toolName: string; failures: number }
diff --git a/packages/ekko-agent/src/runtime/runtime.ts b/packages/ekko-agent/src/runtime/runtime.ts
index d4d70d1911..3644aa0bfd 100644
--- a/packages/ekko-agent/src/runtime/runtime.ts
+++ b/packages/ekko-agent/src/runtime/runtime.ts
@@ -1384,6 +1384,9 @@ export class AgentRuntime {
     let cacheReadTokens = 0
     let cacheWriteTokens = 0
     let reasoningTokens = 0
+    let costUsd = 0
+    let pricedCalls = 0
+    let costSource: 'reported' | 'estimated' = 'reported'
     let childRunId: string | undefined
     const streamedTextSteps = new Set<number>()
     const childPromise = (async (): Promise<AgentToolResult> => {
@@ -1487,6 +1490,11 @@ export class AgentRuntime {
               cacheReadTokens += event.usage.cacheReadTokens || 0
               cacheWriteTokens += event.usage.cacheWriteTokens || 0
               reasoningTokens += event.usage.reasoningTokens || 0
+              if (typeof event.usage.costUsd === 'number' && Number.isFinite(event.usage.costUsd) && event.usage.costUsd >= 0) {
+                costUsd += event.usage.costUsd
+                pricedCalls++
+                if (event.usage.costSource === 'estimated') costSource = 'estimated'
+              }
             }
           },
         })
@@ -1535,6 +1543,7 @@ export class AgentRuntime {
         cacheReadTokens,
         cacheWriteTokens,
         reasoningTokens,
+        ...(apiCalls > 0 && pricedCalls === apiCalls ? { costUsd, costSource } : {}),
         ...(continuationContext ? { continuationContext } : {}),
       })
       const payload = {
diff --git a/packages/server/src/modules/coding-agents/protocol/adapters/responses-stream.ts b/packages/server/src/modules/coding-agents/protocol/adapters/responses-stream.ts
index 2017b97be8..a0b1cc4287 100644
--- a/packages/server/src/modules/coding-agents/protocol/adapters/responses-stream.ts
+++ b/packages/server/src/modules/coding-agents/protocol/adapters/responses-stream.ts
@@ -150,6 +150,7 @@ function openAiChatUsageToResponsesUsage(usage: Record<string, any>): Record<str
   const promptDetails = usage.prompt_tokens_details || usage.input_tokens_details
   const completionDetails = usage.completion_tokens_details || usage.output_tokens_details
   return {
+    ...usage,
     input_tokens: inputTokens,
     output_tokens: outputTokens,
     total_tokens: Number(usage.total_tokens ?? inputTokens + outputTokens),
diff --git a/packages/server/src/modules/coding-agents/protocol/adapters/responses.ts b/packages/server/src/modules/coding-agents/protocol/adapters/responses.ts
index defffac189..4d3e42e15f 100644
--- a/packages/server/src/modules/coding-agents/protocol/adapters/responses.ts
+++ b/packages/server/src/modules/coding-agents/protocol/adapters/responses.ts
@@ -966,6 +966,7 @@ function responseId(data: any): string {
 
 function usageFromChat(data: any) {
   return {
+    ...data?.usage,
     input_tokens: Number(data?.usage?.prompt_tokens || 0),
     output_tokens: Number(data?.usage?.completion_tokens || 0),
     total_tokens: Number(data?.usage?.total_tokens || 0),
@@ -976,6 +977,7 @@ function usageFromAnthropic(data: any) {
   const inputTokens = Number(data?.usage?.input_tokens || 0)
   const outputTokens = Number(data?.usage?.output_tokens || 0)
   return {
+    ...data?.usage,
     input_tokens: inputTokens,
     output_tokens: outputTokens,
     total_tokens: inputTokens + outputTokens,
diff --git a/packages/server/src/modules/coding-agents/services/runtime/native-usage.ts b/packages/server/src/modules/coding-agents/services/runtime/native-usage.ts
index 4c4ff2ddf1..1ca14ca69c 100644
--- a/packages/server/src/modules/coding-agents/services/runtime/native-usage.ts
+++ b/packages/server/src/modules/coding-agents/services/runtime/native-usage.ts
@@ -1,5 +1,5 @@
 import { createHash } from 'crypto'
-import { normalizeTokenUsage, type NormalizedTokenUsage } from '../../../studio/public/usage'
+import { normalizeTokenUsage, normalizeUsageCost, type UsageCost, type NormalizedTokenUsage } from '../../../studio/public/usage'
 
 export interface NativeUsageRow {
   id: string
@@ -8,6 +8,7 @@ export interface NativeUsageRow {
   usage: NormalizedTokenUsage
   apiCalls?: number
   scope: 'run' | 'model_call'
+  cost?: UsageCost
 }
 
 const tokenKeys = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'] as const
@@ -34,6 +35,7 @@ export class NativeTurnUsage {
   private readonly claudeModels = new Set<string>()
   private modelUsage?: Record<string, any>
   private pendingUsage?: unknown
+  private pendingCost?: UsageCost
   private readonly grokResponses = new Map<string, unknown>()
 
   observeClaude(event: any) {
@@ -67,6 +69,7 @@ export class NativeTurnUsage {
     if (event.type === 'result') {
       this.pendingUsage = event.usage
       this.modelUsage = event.modelUsage
+      this.pendingCost = normalizeUsageCost(event, 'estimated')
     }
   }
 
@@ -86,7 +89,7 @@ export class NativeTurnUsage {
     const id = String(message.id || createHash('sha256').update(JSON.stringify(message)).digest('hex'))
     if (this.messages.has(id)) return
     const model = modelName(message.model)
-    const row: NativeUsageRow = { id, model, provider: modelName(message.provider), usage, apiCalls: 1, scope: 'model_call' }
+    const row: NativeUsageRow = { id, model, provider: modelName(message.provider), usage, apiCalls: 1, scope: 'model_call', cost: normalizeUsageCost(raw, 'estimated') }
     this.messages.set(id, row)
     this.model = model
     return row
@@ -98,6 +101,7 @@ export class NativeTurnUsage {
     }
     if (event.type === 'end' || event.type === 'error') {
       if (event.usage) this.pendingUsage = event.usage
+      this.pendingCost = normalizeUsageCost(event, 'estimated')
       if (event.modelUsage && typeof event.modelUsage === 'object' && !Array.isArray(event.modelUsage)) {
         this.modelUsage = event.modelUsage as Record<string, any>
         const models = Object.keys(this.modelUsage)
@@ -115,18 +119,26 @@ export class NativeTurnUsage {
         cache_write_tokens: raw.cache_write_input_tokens ?? raw.cache_write_tokens,
         reasoning_tokens: raw.reasoning_output_tokens ?? raw.reasoning_tokens,
       }, {}, { inputIncludesCache: true })
-      return usage.isEstimated ? [] : [{ id: 'turn', model: this.model || fallbackModel, provider: this.provider, usage, scope: 'run' }]
+      return usage.isEstimated ? [] : [{ id: 'turn', model: this.model || fallbackModel, provider: this.provider, usage, scope: 'run', cost: normalizeUsageCost(raw, 'estimated') }]
     }
 
     let usage = measured(this.pendingUsage ?? finalUsage)
+    let observedCost: UsageCost | undefined
     if (agent === 'grok' && !this.pendingUsage && this.grokResponses.size) {
       // A crash/error may omit the final aggregate. Per-response boundaries
       // are additive, whereas end.usage is already the aggregate.
       const observed = [...this.grokResponses.values()].map(measured).filter((row): row is NormalizedTokenUsage => !!row)
       if (observed.length) usage = Object.fromEntries(tokenKeys.map(key => [key, observed.reduce((sum, row) => sum + row[key], 0)])) as unknown as NormalizedTokenUsage
+      const costs = [...this.grokResponses.values()].map(value => normalizeUsageCost(value, 'estimated'))
+      if (observed.length === costs.length && costs.every(cost => cost !== undefined)) {
+        observedCost = { costUsd: costs.reduce((sum, cost) => sum + cost!.costUsd, 0), costSource: 'estimated' }
+      }
     }
     if (!usage) return agent === 'claude-code' ? [...this.messages.values()] : []
-    if (agent === 'claude-code' && this.messages.size && sameTotals([...this.messages.values()], usage)) {
+    const cost = this.pendingCost || (agent === 'grok' && !this.pendingUsage && this.grokResponses.size
+      ? observedCost : normalizeUsageCost(finalUsage, 'estimated'))
+    const hasModelCost = Object.values(this.modelUsage || {}).some(row => normalizeUsageCost(row, 'estimated'))
+    if (agent === 'claude-code' && !cost && !hasModelCost && this.messages.size && sameTotals([...this.messages.values()], usage)) {
       return [...this.messages.values()]
     }
 
@@ -138,20 +150,30 @@ export class NativeTurnUsage {
         cacheWriteTokens: raw.cacheCreationInputTokens,
         reasoningTokens: raw.reasoningTokens ?? raw.thinkingTokens,
       })
+      const messages = [...this.messages.values()].filter(row => row.model === modelName(model))
+      const apiCalls = Number.isInteger(raw.modelCalls) && raw.modelCalls >= 0
+        ? raw.modelCalls : normalized && messages.length && sameTotals(messages, normalized) ? messages.length : undefined
       return normalized ? {
         id: `model:${model}`, model: modelName(model), usage: normalized, scope: 'run' as const,
-        ...(Number.isInteger(raw.modelCalls) && raw.modelCalls >= 0 ? { apiCalls: raw.modelCalls } : {}),
+        cost: normalizeUsageCost(raw, 'estimated'),
+        ...(apiCalls !== undefined ? { apiCalls } : {}),
       } : undefined
     }).filter((row): row is NonNullable<typeof row> => !!row)
     // Grok's per-model summaries omit reasoning in some versions. With one
     // model attribution is unambiguous; with several keep an aggregate fallback.
     if (models.length === 1 && !models[0].usage.reasoningTokens) models[0].usage.reasoningTokens = usage.reasoningTokens
-    if (models.length && sameTotals(models, usage)) return models
+    if (models.length && sameTotals(models, usage) && (!cost || models.every(row => row.cost) && Math.abs(models.reduce((sum, row) => sum + row.cost!.costUsd, 0) - cost.costUsd) < 1e-9)) return models
 
     const names = new Set([...models.map(row => row.model), ...this.claudeModels].filter(Boolean))
     const model = names.size === 1 ? [...names][0] : names.size > 1 ? '' : this.model || fallbackModel
+    const modelCosts = Object.values(this.modelUsage || {}).map(row => normalizeUsageCost(row, 'estimated'))
+    const aggregateCost = modelCosts.length && modelCosts.every(value => value !== undefined)
+      ? { costUsd: modelCosts.reduce((sum, value) => sum + value!.costUsd, 0), costSource: 'estimated' as const }
+      : undefined
     // Claude modelUsage can include auxiliary work absent from result.usage.
-    // Keep the authoritative turn tokens instead of adding those totals again.
-    return [{ id: 'turn', model, usage, scope: 'run' }]
+    // Keep the authoritative turn tokens, while retaining the complete run's bill once.
+    return [{ id: 'turn', model, usage, scope: 'run', cost: cost || aggregateCost,
+      ...(this.messages.size && sameTotals([...this.messages.values()], usage) ? { apiCalls: this.messages.size } : {}),
+    }]
   }
 }
diff --git a/packages/server/src/modules/coding-agents/services/runtime/run-manager.ts b/packages/server/src/modules/coding-agents/services/runtime/run-manager.ts
index 2b1f68fbb0..6d6563c302 100644
--- a/packages/server/src/modules/coding-agents/services/runtime/run-manager.ts
+++ b/packages/server/src/modules/coding-agents/services/runtime/run-manager.ts
@@ -8,7 +8,7 @@ import { spawn, type ChildProcess } from 'child_process'
 import { createSession, addMessage, getSession, updateSession, updateSessionStats } from '../../../studio/public/sessions'
 import type { ApiMode, CodingAgentImageInput } from '../../protocol/types'
 import { logger } from '../../../studio/public/logging'
-import { normalizeTokenUsage, recordSessionUsage } from '../../../studio/public/usage'
+import { normalizeTokenUsage, normalizeUsageCost, recordSessionUsage } from '../../../studio/public/usage'
 import {
   applyResponseStreamEvent,
   calcAndUpdateUsage,
@@ -1138,6 +1138,7 @@ export class CodingAgentRunManager {
       apiCalls: 1,
       usage,
       profile: run.launch.profile,
+      cost: normalizeUsageCost(final),
       model: final?.model || run.launch.model,
       provider: run.launch.provider,
       isEstimated: false,
@@ -1271,6 +1272,7 @@ export class CodingAgentRunManager {
         usageScope: row.scope,
         apiCalls: row.apiCalls,
         usage: row.usage,
+        cost: row.cost,
         profile: run.launch.profile,
         model: row.model,
         provider: row.provider || run.launch.provider,
@@ -2859,6 +2861,7 @@ export class CodingAgentRunManager {
             apiCalls: 1,
             usage,
             profile: run.launch.profile,
+            cost: normalizeUsageCost(part, 'estimated'),
             model: nativeModel?.model || run.launch.model,
             provider: nativeModel?.provider || run.launch.provider,
             isEstimated: false,
diff --git a/packages/server/src/modules/hermes/services/history/sessions-db.ts b/packages/server/src/modules/hermes/services/history/sessions-db.ts
index cce0750cec..cf9d8cdb9a 100644
--- a/packages/server/src/modules/hermes/services/history/sessions-db.ts
+++ b/packages/server/src/modules/hermes/services/history/sessions-db.ts
@@ -2,6 +2,7 @@ import { getActiveProfileDir, getHermesBaseDir } from '../profiles/profile'
 import { join } from 'path'
 import { existsSync } from 'fs'
 import type { LocalUsageStats } from '../../../studio/contracts/runs/usage'
+import { emptyCostCoverage } from '../../../studio/public/usage'
 import type { ExternalSkillUsageEvent } from '../../../studio/contracts/skills'
 
 const SQLITE_AVAILABLE = (() => {
@@ -940,6 +941,7 @@ export async function findLatestExactSessionIdWithProfile(
 export interface HermesUsageStats extends LocalUsageStats {
   cost: number
   total_api_calls: number
+  cost_fallbacks?: Array<{ session_id: string; date: string; cost: number; source: 'reported' | 'estimated' }>
 }
 
 export interface HermesSkillUsageRow {
@@ -1459,6 +1461,7 @@ export async function getUsageStatsFromDb(
   nowSeconds = Math.floor(Date.now() / 1000),
   profile?: string,
   excludedSessionIds: Iterable<string> = [],
+  unpricedSessionIds: Iterable<string> = [],
 ): Promise<HermesUsageStats> {
   const empty: HermesUsageStats = {
     input_tokens: 0,
@@ -1471,6 +1474,7 @@ export async function getUsageStatsFromDb(
     by_agent: [],
     by_day: [],
     cost: 0,
+    cost_coverage: emptyCostCoverage(),
     total_api_calls: 0,
   }
 
@@ -1485,6 +1489,21 @@ export async function getUsageStatsFromDb(
   const db = await openSessionDb(profile)
 
   try {
+    // Legacy estimated_cost_usd defaults to zero even when no pricing exists.
+    const hasCostStatus = tableHasColumn(db, 'sessions', 'cost_status')
+    const actualCost = `CASE WHEN actual_cost_usd >= 0 THEN actual_cost_usd END`
+    const estimatedCost = `CASE WHEN estimated_cost_usd > 0${hasCostStatus ? " OR (estimated_cost_usd = 0 AND cost_status IN ('estimated', 'free'))" : ''} THEN estimated_cost_usd END`
+    const costExpr = `COALESCE(${actualCost}, ${estimatedCost})`
+    const costColumns = `COALESCE(SUM(${costExpr}), 0) AS cost,
+      COALESCE(SUM(CASE WHEN ${actualCost} IS NOT NULL THEN 1 ELSE 0 END), 0) AS cost_reported,
+      COALESCE(SUM(CASE WHEN ${actualCost} IS NULL AND ${estimatedCost} IS NOT NULL THEN 1 ELSE 0 END), 0) AS cost_estimated,
+      COALESCE(SUM(CASE WHEN ${costExpr} IS NULL THEN 1 ELSE 0 END), 0) AS cost_unknown`
+    const coverage = (row: Record<string, unknown>) => ({ reported: Number(row.cost_reported || 0), estimated: Number(row.cost_estimated || 0), unknown: Number(row.cost_unknown || 0) })
+    const fallbackIds = [...new Set(unpricedSessionIds)].filter(id => excludedIds.includes(id))
+    const costFallbacks = fallbackIds.length ? db.prepare(`SELECT id AS session_id, date(started_at, 'unixepoch') AS date,
+      ${costExpr} AS cost, CASE WHEN ${actualCost} IS NOT NULL THEN 'reported' ELSE 'estimated' END AS source
+      FROM sessions WHERE started_at > ? AND id IN (SELECT value FROM json_each(?)) AND ${costExpr} IS NOT NULL
+    `).all(since, JSON.stringify(fallbackIds)) as NonNullable<HermesUsageStats['cost_fallbacks']> : []
     const apiCallsExpr = tableHasColumn(db, 'sessions', 'api_call_count')
       ? 'COALESCE(SUM(api_call_count), 0)'
       : '0'
@@ -1495,7 +1514,7 @@ export async function getUsageStatsFromDb(
         COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
         COALESCE(SUM(cache_write_tokens), 0) AS cache_write_tokens,
         COALESCE(SUM(reasoning_tokens), 0) AS reasoning_tokens,
-        COALESCE(SUM(COALESCE(actual_cost_usd, estimated_cost_usd, 0)), 0) AS cost,
+        ${costColumns},
         COUNT(*) AS sessions,
         ${apiCallsExpr} AS total_api_calls
       FROM sessions
@@ -1535,7 +1554,7 @@ export async function getUsageStatsFromDb(
         COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
         COALESCE(SUM(cache_write_tokens), 0) AS cache_write_tokens,
         COUNT(*) AS sessions,
-        COALESCE(SUM(COALESCE(actual_cost_usd, estimated_cost_usd, 0)), 0) AS cost
+        ${costColumns}
       FROM sessions
       WHERE started_at > ?${exclusionClause}
       GROUP BY date
@@ -1549,6 +1568,7 @@ export async function getUsageStatsFromDb(
       sessions: normalizeNumber(row.sessions),
       errors: 0,
       cost: normalizeNumber(row.cost),
+      cost_coverage: coverage(row),
     }))
 
     return {
@@ -1572,6 +1592,8 @@ export async function getUsageStatsFromDb(
         : [],
       by_day: byDay,
       cost: normalizeNumber(totals.cost),
+      cost_coverage: coverage(totals),
+      cost_fallbacks: costFallbacks,
       total_api_calls: normalizeNumber(totals.total_api_calls),
     }
   } finally {
diff --git a/packages/server/src/modules/studio/contracts/runs/usage.ts b/packages/server/src/modules/studio/contracts/runs/usage.ts
index 0d740cc784..964d6c2a02 100644
--- a/packages/server/src/modules/studio/contracts/runs/usage.ts
+++ b/packages/server/src/modules/studio/contracts/runs/usage.ts
@@ -1,3 +1,9 @@
+export interface UsageCostCoverage {
+  reported: number
+  estimated: number
+  unknown: number
+}
+
 export interface UsageStatsModelRow {
   model: string
   input_tokens: number
@@ -27,6 +33,7 @@ export interface UsageStatsDailyRow {
   sessions: number
   errors: number
   cost: number
+  cost_coverage?: UsageCostCoverage
 }
 
 export interface LocalUsageStats {
@@ -40,5 +47,6 @@ export interface LocalUsageStats {
   by_agent: UsageStatsAgentRow[]
   by_day: UsageStatsDailyRow[]
   cost: number
+  cost_coverage?: UsageCostCoverage
   total_api_calls: number
 }
diff --git a/packages/server/src/modules/studio/controllers/sessions.ts b/packages/server/src/modules/studio/controllers/sessions.ts
index c2ce084f5e..ebc6cfcce0 100644
--- a/packages/server/src/modules/studio/controllers/sessions.ts
+++ b/packages/server/src/modules/studio/controllers/sessions.ts
@@ -1,4 +1,7 @@
 import { businessEvents } from '../services/webhooks/business-events'
+import { getUsagePricing, saveUsagePricing, validateUsagePricing } from '../services/usage/usage-pricing'
+import { emptyCostCoverage, addCostCoverage } from '../services/usage/usage-cost'
+import { applyHermesCostFallbacks } from '../services/usage/hermes-cost-fallback'
 import { ensureBusinessConsumers } from '../services/webhooks/business-consumers'
 import { authorizeSessionShare, authorizeShareFile } from '../services/session-shares/access'
 import { sessionShareService } from '../services/session-shares/service'
@@ -35,7 +38,7 @@ import {
   updateSessionStats as localUpdateSessionStats,
 } from '../public/sessions'
 import { buildDbExportHistory, ExportCompressor } from '../services/context-compressor/export-compressor'
-import { getLocalUsageStats, getRecordedUsageSessionIds, getUsage, getUsageBatch } from '../public/sessions'
+import { getUnpricedHermesUsageSessions, getLocalUsageStats, getRecordedUsageSessionIds, getUsage, getUsageBatch } from '../public/sessions'
 import {
   SESSION_CATEGORY_NAME_MAX_LENGTH,
   createSessionCategory,
@@ -1687,6 +1690,7 @@ export async function usageStats(ctx: any) {
 
   const local = getLocalUsageStats(profile, days)
   const localSessionIds = getRecordedUsageSessionIds(profile)
+  const unpricedHermesSessions = getUnpricedHermesUsageSessions(profile, days)
 
   let hermes = {
     input_tokens: 0,
@@ -1699,11 +1703,14 @@ export async function usageStats(ctx: any) {
     by_agent: [] as UsageStatsAgentRow[],
     by_day: [] as UsageStatsDailyRow[],
     cost: 0,
+    cost_coverage: emptyCostCoverage(),
     total_api_calls: 0,
   }
 
   try {
-    hermes = await getHermesUsageStats(days, undefined, profile, localSessionIds)
+    const result = await getHermesUsageStats(days, undefined, profile, localSessionIds, unpricedHermesSessions.map(row => row.sessionId))
+    applyHermesCostFallbacks(local, unpricedHermesSessions, result.cost_fallbacks)
+    hermes = result
   } catch (err) {
     logger.warn(err, 'usageStats: failed to load Hermes usage analytics from state.db')
   }
@@ -1756,7 +1763,7 @@ export async function usageStats(ctx: any) {
     const d = new Date(now)
     d.setDate(d.getDate() - i)
     const key = d.toISOString().slice(0, 10)
-    dayMap.set(key, { date: key, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, sessions: 0, errors: 0, cost: 0 })
+    dayMap.set(key, { date: key, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, sessions: 0, errors: 0, cost: 0, cost_coverage: emptyCostCoverage() })
   }
   for (const d of [...local.by_day, ...hermes.by_day]) {
     const existing = dayMap.get(d.date)
@@ -1764,9 +1771,13 @@ export async function usageStats(ctx: any) {
       existing.input_tokens += d.input_tokens; existing.output_tokens += d.output_tokens
       existing.cache_read_tokens += d.cache_read_tokens; existing.cache_write_tokens += d.cache_write_tokens
       existing.sessions += d.sessions; existing.errors += d.errors; existing.cost += d.cost
+      addCostCoverage(existing.cost_coverage!, d.cost_coverage)
     }
   }
 
+  const costCoverage = emptyCostCoverage()
+  addCostCoverage(costCoverage, local.cost_coverage)
+  addCostCoverage(costCoverage, hermes.cost_coverage)
   ctx.body = {
     total_input_tokens: local.input_tokens + hermes.input_tokens,
     total_output_tokens: local.output_tokens + hermes.output_tokens,
@@ -1775,6 +1786,7 @@ export async function usageStats(ctx: any) {
     total_reasoning_tokens: local.reasoning_tokens + hermes.reasoning_tokens,
     total_sessions: local.sessions + hermes.sessions,
     total_cost: local.cost + hermes.cost,
+    cost_coverage: costCoverage,
     total_api_calls: local.total_api_calls + hermes.total_api_calls,
     period_days: days,
     model_usage: [...modelMap.values()].sort((a, b) => (b.input_tokens + b.output_tokens) - (a.input_tokens + a.output_tokens)),
@@ -1783,6 +1795,23 @@ export async function usageStats(ctx: any) {
   }
 }
 
+export async function usagePricing(ctx: any) {
+  ctx.body = { rates: getUsagePricing(requestedProfile(ctx) || getActiveProfileName()) }
+}
+
+export async function updateUsagePricing(ctx: any) {
+  let rates
+  try {
+    rates = validateUsagePricing(ctx.request.body?.rates)
+  } catch (err) {
+    ctx.status = 400
+    ctx.body = { error: (err as Error).message }
+    return
+  }
+  saveUsagePricing(requestedProfile(ctx) || getActiveProfileName(), rates)
+  ctx.body = { rates }
+}
+
 async function listWindowsWorkspaceDrives() {
   const { existsSync } = await import('fs')
   const drives = []
diff --git a/packages/server/src/modules/studio/infrastructure/database/schemas.ts b/packages/server/src/modules/studio/infrastructure/database/schemas.ts
index cdce92374c..e477f48056 100644
--- a/packages/server/src/modules/studio/infrastructure/database/schemas.ts
+++ b/packages/server/src/modules/studio/infrastructure/database/schemas.ts
@@ -27,12 +27,20 @@ export const USAGE_SCHEMA: Record<string, string> = {
   provider: "TEXT NOT NULL DEFAULT ''",
   profile: "TEXT NOT NULL DEFAULT 'default'",
   is_estimated: 'INTEGER NOT NULL DEFAULT 0',
+  cost_usd: 'REAL',
+  cost_source: "TEXT NOT NULL DEFAULT 'unknown'",
   created_at: 'INTEGER NOT NULL DEFAULT 0',
 }
 
 export const USAGE_RUN_INDEX = `CREATE UNIQUE INDEX IF NOT EXISTS idx_session_usage_run
   ON ${USAGE_TABLE}(session_id, run_id, source) WHERE run_id <> ''`
 
+export const USAGE_PRICING_TABLE = 'usage_pricing'
+export const USAGE_PRICING_SCHEMA = {
+  profile: 'TEXT PRIMARY KEY',
+  rates: "TEXT NOT NULL DEFAULT '[]'",
+}
+
 // ============================================================================
 // Session Store (session-store.ts)
 // ============================================================================
@@ -1609,6 +1617,7 @@ export function initAllHermesTables(): void {
   try {
     // Usage store
     syncTable(USAGE_TABLE, USAGE_SCHEMA, { primaryKey: 'id' })
+    syncTable(USAGE_PRICING_TABLE, USAGE_PRICING_SCHEMA, { primaryKey: 'profile' })
     db.exec(USAGE_RUN_INDEX)
 
     // Session store
diff --git a/packages/server/src/modules/studio/public/usage.ts b/packages/server/src/modules/studio/public/usage.ts
index fd260a35a3..778c411b91 100644
--- a/packages/server/src/modules/studio/public/usage.ts
+++ b/packages/server/src/modules/studio/public/usage.ts
@@ -1,2 +1,3 @@
 export * from '../services/usage/usage-recorder'
+export * from '../services/usage/usage-cost'
 export { getUsage } from '../repositories/usage-store'
diff --git a/packages/server/src/modules/studio/repositories/usage-pricing-store.ts b/packages/server/src/modules/studio/repositories/usage-pricing-store.ts
new file mode 100644
index 0000000000..f302245dd0
--- /dev/null
+++ b/packages/server/src/modules/studio/repositories/usage-pricing-store.ts
@@ -0,0 +1,20 @@
+import { getDb, isSqliteAvailable, jsonGet, jsonSet } from '../infrastructure/database'
+import { USAGE_PRICING_TABLE as TABLE } from '../infrastructure/database/schemas'
+import type { UsagePricing } from '../services/usage/usage-cost'
+
+export function getUsagePricing(profile: string): UsagePricing[] {
+  const row = isSqliteAvailable()
+    ? getDb()!.prepare(`SELECT rates FROM ${TABLE} WHERE profile = ?`).get(profile) as { rates: string } | undefined
+    : jsonGet(TABLE, profile)
+  return row ? JSON.parse(row.rates) : []
+}
+
+export function saveUsagePricing(profile: string, rates: UsagePricing[]): void {
+  const serialized = JSON.stringify(rates)
+  if (isSqliteAvailable()) {
+    getDb()!.prepare(`INSERT INTO ${TABLE} (profile, rates) VALUES (?, ?)
+      ON CONFLICT(profile) DO UPDATE SET rates = excluded.rates`).run(profile, serialized)
+  } else {
+    jsonSet(TABLE, profile, { rates: serialized })
+  }
+}
diff --git a/packages/server/src/modules/studio/repositories/usage-store.ts b/packages/server/src/modules/studio/repositories/usage-store.ts
index 888e253ed7..6c038c57ee 100644
--- a/packages/server/src/modules/studio/repositories/usage-store.ts
+++ b/packages/server/src/modules/studio/repositories/usage-store.ts
@@ -1,5 +1,6 @@
 import { isSqliteAvailable, getDb, jsonSet, jsonGet, jsonGetAll, jsonDelete } from '../infrastructure/database'
 import { USAGE_TABLE as TABLE } from '../infrastructure/database/schemas'
+import { finiteCost, emptyCostCoverage } from '../services/usage/usage-cost'
 import type {
   LocalUsageStats,
   UsageStatsAgentRow,
@@ -54,6 +55,8 @@ export function updateUsage(
     provider?: string
     profile?: string
     isEstimated?: boolean
+    costUsd?: number
+    costSource?: 'reported' | 'estimated'
   },
 ): void {
   const cacheReadTokens = data.cacheReadTokens ?? 0
@@ -63,6 +66,8 @@ export function updateUsage(
   const model = data.model || ''
   const provider = data.provider || ''
   const profile = data.profile || 'default'
+  const costUsd = finiteCost(data.costUsd) ?? null
+  const costSource = costUsd == null ? 'unknown' : data.costSource || 'reported'
   if (isSqliteAvailable()) {
     const db = getDb()!
     const columns = [
@@ -83,6 +88,8 @@ export function updateUsage(
       'profile',
       'is_estimated',
       'created_at',
+      'cost_usd',
+      'cost_source',
     ]
     const values = columns.map(() => '?')
     const params = [
@@ -103,6 +110,8 @@ export function updateUsage(
       profile,
       data.isEstimated ? 1 : 0,
       now,
+      costUsd,
+      costSource,
     ]
     if (hasUpdatedAtColumn()) {
       columns.push('updated_at')
@@ -130,6 +139,8 @@ export function updateUsage(
       profile,
       is_estimated: data.isEstimated ? 1 : 0,
       created_at: now,
+      cost_usd: costUsd,
+      cost_source: costSource,
     })
   }
 }
@@ -282,7 +293,7 @@ export function getLocalUsageStats(profile?: string, days = 30): LocalUsageStats
   const empty: LocalUsageStats = {
     input_tokens: 0, output_tokens: 0, cache_read_tokens: 0,
     cache_write_tokens: 0, reasoning_tokens: 0, sessions: 0,
-    by_model: [], by_agent: [], by_day: [], cost: 0, total_api_calls: 0,
+    by_model: [], by_agent: [], by_day: [], cost: 0, cost_coverage: emptyCostCoverage(), total_api_calls: 0,
   }
   if (!isSqliteAvailable()) return empty
 
@@ -304,6 +315,7 @@ export function getLocalUsageStats(profile?: string, days = 30): LocalUsageStats
       COALESCE(SUM(cache_write_tokens),0) as cache_write_tokens,
       COALESCE(SUM(reasoning_tokens),0) as reasoning_tokens,
       COALESCE(SUM(api_calls),0) as total_api_calls,
+      ${costSelect},
       COUNT(DISTINCT session_id) as sessions
     FROM ${TABLE}
     ${whereClause}
@@ -339,6 +351,7 @@ export function getLocalUsageStats(profile?: string, days = 30): LocalUsageStats
 
   const byDay = db.prepare(`
     SELECT DATE(created_at / 1000, 'unixepoch') as date,
+      ${costSelect},
       COALESCE(SUM(input_tokens),0) as input_tokens,
       COALESCE(SUM(output_tokens),0) as output_tokens,
       COALESCE(SUM(cache_read_tokens),0) as cache_read_tokens,
@@ -348,7 +361,7 @@ export function getLocalUsageStats(profile?: string, days = 30): LocalUsageStats
     ${whereClause}
     GROUP BY date
     ORDER BY date
-  `).all(...params) as Array<{ date: string; input_tokens: number; output_tokens: number; cache_read_tokens: number; cache_write_tokens: number; sessions: number }>
+  `).all(...params) as unknown as Array<UsageStatsDailyRow & CostTotals>
 
   return {
     input_tokens: totals.input_tokens,
@@ -359,8 +372,37 @@ export function getLocalUsageStats(profile?: string, days = 30): LocalUsageStats
     sessions: totals.sessions,
     by_model: byModel,
     by_agent: byAgent,
-    by_day: byDay.map(d => ({ ...d, errors: 0, cost: 0 })),
-    cost: 0,
+    by_day: byDay.map(({ cost_reported, cost_estimated, cost_unknown, ...d }) => ({ ...d, errors: 0, cost: d.cost || 0, cost_coverage: coverage({ cost_reported, cost_estimated, cost_unknown }) })),
+    cost: totals.cost || 0,
+    cost_coverage: coverage(totals),
     total_api_calls: totals.total_api_calls,
   }
 }
+
+type CostTotals = { cost_reported?: number; cost_estimated?: number; cost_unknown?: number }
+const costSelect = `COALESCE(SUM(cost_usd), 0) AS cost,
+  COALESCE(SUM(CASE WHEN cost_usd IS NOT NULL AND cost_source <> 'estimated' THEN 1 ELSE 0 END), 0) AS cost_reported,
+  COALESCE(SUM(CASE WHEN cost_usd IS NOT NULL AND cost_source = 'estimated' THEN 1 ELSE 0 END), 0) AS cost_estimated,
+  COALESCE(SUM(CASE WHEN cost_usd IS NULL THEN 1 ELSE 0 END), 0) AS cost_unknown`
+
+function coverage(row: CostTotals) {
+  return { reported: row.cost_reported || 0, estimated: row.cost_estimated || 0, unknown: row.cost_unknown || 0 }
+}
+
+/** A cumulative Hermes bill can only replace wholly unpriced sessions contained in this period. */
+export function getUnpricedHermesUsageSessions(profile: string, days: number): Array<{ sessionId: string; days: Array<{ date: string; entries: number }> }> {
+  if (!isSqliteAvailable()) return []
+  const cutoff = Date.now() - days * 86_400_000
+  const rows = getDb()!.prepare(`SELECT session_id, DATE(created_at / 1000, 'unixepoch') AS date, COUNT(*) AS entries
+    FROM ${TABLE} WHERE profile = ? AND source = 'hermes' AND session_id IN (
+      SELECT session_id FROM ${TABLE} WHERE profile = ? GROUP BY session_id
+      HAVING MIN(created_at) > ? AND COUNT(cost_usd) = 0 AND SUM(CASE WHEN source <> 'hermes' THEN 1 ELSE 0 END) = 0
+    ) GROUP BY session_id, date`).all(profile, profile, cutoff) as Array<{ session_id: string; date: string; entries: number }>
+  const sessions = new Map<string, Array<{ date: string; entries: number }>>()
+  for (const row of rows) {
+    const days = sessions.get(row.session_id) || []
+    days.push({ date: row.date, entries: row.entries })
+    sessions.set(row.session_id, days)
+  }
+  return [...sessions].map(([sessionId, days]) => ({ sessionId, days }))
+}
diff --git a/packages/server/src/modules/studio/routes/sessions.ts b/packages/server/src/modules/studio/routes/sessions.ts
index 0ae3197276..22385d55b6 100644
--- a/packages/server/src/modules/studio/routes/sessions.ts
+++ b/packages/server/src/modules/studio/routes/sessions.ts
@@ -21,6 +21,8 @@ sessionRoutes.get('/api/studio/search/sessions', ctrl.search)
 sessionRoutes.get('/api/studio/sessions/search', ctrl.search)
 sessionRoutes.get('/api/studio/sessions/usage', ctrl.usageBatch)
 sessionRoutes.get('/api/studio/usage/stats', ctrl.usageStats)
+sessionRoutes.get('/api/studio/usage/pricing', ctrl.usagePricing)
+sessionRoutes.put('/api/studio/usage/pricing', ctrl.updateUsagePricing)
 sessionRoutes.get('/api/studio/sessions/context-length', ctrl.contextLength)
 sessionRoutes.get('/api/studio/sessions/:id/context', ctrl.getContext)
 sessionRoutes.get('/api/studio/sessions/:id/workspace-run-changes', ctrl.listWorkspaceRunChanges)
diff --git a/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts b/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts
index 96bb50c16e..1a5b115741 100644
--- a/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts
+++ b/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts
@@ -1131,6 +1131,8 @@ export async function handleEkkoAgentRun(
               cacheReadTokens: event.cacheReadTokens,
               cacheWriteTokens: event.cacheWriteTokens,
               reasoningTokens: event.reasoningTokens,
+              costUsd: event.costUsd,
+              costSource: event.costSource,
             },
             profile,
             model: modelConfig.model,
diff --git a/packages/server/src/modules/studio/services/usage/hermes-cost-fallback.ts b/packages/server/src/modules/studio/services/usage/hermes-cost-fallback.ts
new file mode 100644
index 0000000000..ffbfae5baf
--- /dev/null
+++ b/packages/server/src/modules/studio/services/usage/hermes-cost-fallback.ts
@@ -0,0 +1,31 @@
+import type { LocalUsageStats } from '../../contracts/runs/usage'
+import { emptyCostCoverage } from './usage-cost'
+
+export function applyHermesCostFallbacks(
+  local: LocalUsageStats,
+  candidates: Array<{ sessionId: string; days: Array<{ date: string; entries: number }> }>,
+  fallbacks: Array<{ session_id: string; date: string; cost: number; source: 'reported' | 'estimated' }> = [],
+): void {
+  const remaining = new Map(candidates.map(row => [row.sessionId, row]))
+  for (const fallback of fallbacks) {
+    const candidate = remaining.get(fallback.session_id)
+    if (!candidate || !Number.isFinite(fallback.cost) || fallback.cost < 0) continue
+    remaining.delete(fallback.session_id)
+    local.cost += fallback.cost
+    local.cost_coverage ??= emptyCostCoverage()
+    local.cost_coverage.unknown = Math.max(0, local.cost_coverage.unknown - candidate.days.reduce((sum, day) => sum + day.entries, 0))
+    local.cost_coverage[fallback.source]++
+    let day = local.by_day.find(row => row.date === fallback.date)
+    if (!day) {
+      day = { date: fallback.date, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, sessions: 0, errors: 0, cost: 0 }
+      local.by_day.push(day)
+    }
+    day.cost += fallback.cost
+    day.cost_coverage ??= emptyCostCoverage()
+    day.cost_coverage[fallback.source]++
+    // A session-level bill cannot identify each day's charge in a multi-day session.
+    if (candidate.days.length === 1 && candidate.days[0].date === fallback.date) {
+      day.cost_coverage.unknown = Math.max(0, day.cost_coverage.unknown - candidate.days[0].entries)
+    }
+  }
+}
diff --git a/packages/server/src/modules/studio/services/usage/usage-cost.ts b/packages/server/src/modules/studio/services/usage/usage-cost.ts
new file mode 100644
index 0000000000..16a4c173c3
--- /dev/null
+++ b/packages/server/src/modules/studio/services/usage/usage-cost.ts
@@ -0,0 +1,70 @@
+import type { UsageCostCoverage } from '../../contracts/runs/usage'
+
+export interface UsageCost {
+  costUsd: number
+  costSource: 'reported' | 'estimated'
+}
+
+export interface UsagePricing {
+  provider: string
+  model: string
+  input: number
+  output: number
+  cacheRead?: number
+  cacheWrite?: number
+}
+
+export function finiteCost(value: unknown): number | undefined {
+  if (typeof value !== 'number' && typeof value !== 'string') return
+  if (typeof value === 'string' && !value.trim()) return
+  const amount = Number(value)
+  return Number.isFinite(amount) && amount >= 0 ? amount : undefined
+}
+
+/** Only explicit USD fields and supported provider usage.cost payloads are accepted. */
+export function normalizeUsageCost(value: unknown, source: UsageCost['costSource'] = 'reported'): UsageCost | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return
+  const root = value as Record<string, any>
+  const records = [root, root.usage, root.response, root.response?.usage, root.result, root.result?.usage]
+    .filter(row => row && typeof row === 'object' && !Array.isArray(row))
+  for (const row of records) {
+    const actual = finiteCost(row.actual_cost_usd)
+    if (actual !== undefined) return { costUsd: actual, costSource: 'reported' }
+    for (const candidate of [row.costUsd, row.costUSD, row.cost_usd, row.total_cost_usd, row.cost?.total, row.cost]) {
+      const amount = finiteCost(candidate)
+      // Native CLI price catalogs also emit zero when a model has no price.
+      if (amount === 0 && source === 'estimated' && row.costSource !== 'estimated') continue
+      if (amount !== undefined) return { costUsd: amount, costSource: row.costSource === 'estimated' ? 'estimated' : source }
+    }
+  }
+  for (const row of records) {
+    const amount = finiteCost(row.estimated_cost_usd)
+    if (amount !== undefined) return { costUsd: amount, costSource: 'estimated' }
+  }
+}
+
+export function estimateUsageCost(usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number }, pricing?: UsagePricing): UsageCost | undefined {
+  if (!pricing) return
+  let costUsd = 0
+  for (const [tokens, rate] of [
+    [usage.inputTokens, pricing.input], [usage.outputTokens, pricing.output],
+    [usage.cacheReadTokens, pricing.cacheRead], [usage.cacheWriteTokens, pricing.cacheWrite],
+  ]) {
+    if (!tokens) continue
+    if (rate === undefined || finiteCost(rate) === undefined) return
+    costUsd += tokens * rate / 1_000_000
+  }
+  // Reasoning tokens are already included in output; never charge them twice.
+  return Number.isFinite(costUsd) ? { costUsd, costSource: 'estimated' } : undefined
+}
+
+export function emptyCostCoverage(): UsageCostCoverage {
+  return { reported: 0, estimated: 0, unknown: 0 }
+}
+
+export function addCostCoverage(target: UsageCostCoverage, source?: UsageCostCoverage): void {
+  if (!source) return
+  target.reported += source.reported
+  target.estimated += source.estimated
+  target.unknown += source.unknown
+}
diff --git a/packages/server/src/modules/studio/services/usage/usage-pricing.ts b/packages/server/src/modules/studio/services/usage/usage-pricing.ts
new file mode 100644
index 0000000000..44af1e6f95
--- /dev/null
+++ b/packages/server/src/modules/studio/services/usage/usage-pricing.ts
@@ -0,0 +1,24 @@
+import type { UsagePricing } from './usage-cost'
+export { getUsagePricing, saveUsagePricing } from '../../repositories/usage-pricing-store'
+
+export function validateUsagePricing(value: unknown): UsagePricing[] {
+  if (!Array.isArray(value) || value.length > 200) throw new Error('Expected at most 200 pricing rows')
+  const keys = new Set<string>()
+  return value.map(row => {
+    if (!row || typeof row !== 'object') throw new Error('Invalid pricing row')
+    const provider = typeof row.provider === 'string' ? row.provider.trim() : ''
+    const model = typeof row.model === 'string' ? row.model.trim() : ''
+    if (!provider || !model || provider.length > 200 || model.length > 300) throw new Error('Provider and model are required')
+    const key = JSON.stringify([provider, model])
+    if (keys.has(key)) throw new Error('Duplicate provider/model pricing')
+    keys.add(key)
+    const rates: Record<string, number> = {}
+    for (const field of ['input', 'output', 'cacheRead', 'cacheWrite']) {
+      const rate = row[field]
+      if (rate == null && (field === 'cacheRead' || field === 'cacheWrite')) continue
+      if (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0 || rate > 1_000_000) throw new Error('Invalid USD per million token rate')
+      rates[field] = rate
+    }
+    return { provider, model, input: rates.input, output: rates.output, ...rates }
+  })
+}
diff --git a/packages/server/src/modules/studio/services/usage/usage-recorder.ts b/packages/server/src/modules/studio/services/usage/usage-recorder.ts
index cab0687f5b..551fdaf57b 100644
--- a/packages/server/src/modules/studio/services/usage/usage-recorder.ts
+++ b/packages/server/src/modules/studio/services/usage/usage-recorder.ts
@@ -1,5 +1,7 @@
 import { logger } from '../../public/logging'
 import { updateUsage } from '../../repositories/usage-store'
+import { getUsagePricing } from '../../repositories/usage-pricing-store'
+import { normalizeUsageCost, estimateUsageCost, type UsageCost } from './usage-cost'
 
 export interface NormalizedTokenUsage {
   inputTokens: number
@@ -23,6 +25,7 @@ export interface RecordSessionUsageInput {
   usage?: unknown
   fallbackUsage?: Partial<NormalizedTokenUsage>
   isEstimated?: boolean
+  cost?: UsageCost
 }
 
 function asRecord(value: unknown): Record<string, any> | undefined {
@@ -110,6 +113,16 @@ export function normalizeTokenUsage(
 export function recordSessionUsage(input: RecordSessionUsageInput): NormalizedTokenUsage {
   const usage = normalizeTokenUsage(input.usage, input.fallbackUsage)
   try {
+    let cost = normalizeUsageCost(input.cost) || normalizeUsageCost(input.usage)
+    if (!cost && input.model && input.provider) {
+      try {
+        const pricing = getUsagePricing(input.profile || 'default')
+          .find(row => row.provider === input.provider && row.model === input.model)
+        cost = estimateUsageCost(usage, pricing)
+      } catch (err) {
+        logger.warn({ err }, '[usage-recorder] failed to read model pricing')
+      }
+    }
     updateUsage(input.sessionId, {
       runId: input.runId || '',
       source: input.source,
@@ -126,6 +139,7 @@ export function recordSessionUsage(input: RecordSessionUsageInput): NormalizedTo
       provider: input.provider || '',
       profile: input.profile || 'default',
       isEstimated: input.isEstimated ?? usage.isEstimated,
+      ...(cost || {}),
     })
   } catch (err) {
     logger.warn({
diff --git a/scripts/generate-openapi.mjs b/scripts/generate-openapi.mjs
index 2f87d5ea91..ad3da688da 100644
--- a/scripts/generate-openapi.mjs
+++ b/scripts/generate-openapi.mjs
@@ -1460,6 +1460,20 @@ for (const [path, methods] of Object.entries(openapi.paths)) {
   }
 }
 
+// Usage rates are Profile-scoped and are snapshots for future usage only.
+const usageRateSchema = { type: 'object', required: ['provider', 'model', 'input', 'output'], properties: {
+  provider: { type: 'string', minLength: 1, maxLength: 200 }, model: { type: 'string', minLength: 1, maxLength: 300 },
+  ...Object.fromEntries(['input', 'output', 'cacheRead', 'cacheWrite'].map(key => [key, { type: 'number', minimum: 0, maximum: 1000000, description: 'USD per million tokens', ...(['cacheRead', 'cacheWrite'].includes(key) ? { nullable: true } : {}) }])),
+} }
+const usageRatesSchema = { type: 'object', required: ['rates'], properties: { rates: { type: 'array', maxItems: 200, items: usageRateSchema } } }
+const usagePricingPath = openapi.paths['/api/studio/usage/pricing']
+usagePricingPath.put.requestBody = { required: true, content: { 'application/json': { schema: usageRatesSchema } } }
+for (const operation of [usagePricingPath.get, usagePricingPath.put]) {
+  operation.description = 'Profile-scoped model pricing in USD per million tokens. Exact provider/model match. Applies only to future calls without reported cost; never reprices historical usage.'
+  operation.responses['200'] = { description: 'Saved pricing', content: { 'application/json': { schema: usageRatesSchema } } }
+}
+usagePricingPath.put.responses['400'] = { description: 'Invalid or duplicate provider/model pricing' }
+
 // Write output
 const outputPath = join(rootDir, 'docs/openapi.json')
 writeFileSync(outputPath, JSON.stringify(openapi, null, 2))
diff --git a/tests/client/usage-cost.test.ts b/tests/client/usage-cost.test.ts
new file mode 100644
index 0000000000..9225ea8f7f
--- /dev/null
+++ b/tests/client/usage-cost.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { formatUsageCost, usageCostState } from '../../packages/client/src/utils/usage-cost'
+
+describe('usage cost presentation', () => {
+  it('distinguishes unknown, free and legacy server zero', () => {
+    expect(formatUsageCost(0, { reported: 0, estimated: 0, unknown: 2 })).toBeNull()
+    expect(formatUsageCost(0, { reported: 1, estimated: 0, unknown: 0 })).toBe('$0.00')
+    expect(formatUsageCost(0)).toBeNull()
+    expect(formatUsageCost(0, undefined, false)).toBe('$0.00')
+    expect(formatUsageCost(0.001)).toBe('<$0.01')
+  })
+  it('identifies partial coverage and estimates without losing the known amount', () => {
+    const partial = { reported: 2, estimated: 1, unknown: 1 }
+    expect(usageCostState(1.23, partial)).toBe('partial')
+    expect(formatUsageCost(1.23, partial)).toBe('$1.23')
+    expect(usageCostState(1, { reported: 0, estimated: 1, unknown: 0 })).toBe('estimated')
+    expect(usageCostState(1, { reported: 1, estimated: 1, unknown: 0 })).toBe('mixed')
+  })
+})
diff --git a/tests/client/usage-view-period.test.ts b/tests/client/usage-view-period.test.ts
index bcebbffe24..b9cde20788 100644
--- a/tests/client/usage-view-period.test.ts
+++ b/tests/client/usage-view-period.test.ts
@@ -61,6 +61,10 @@ vi.mock('@/components/hermes/usage/DailyTrend.vue', () => ({
   default: defineComponent({ name: 'DailyTrend', template: '<section class="daily-trend-stub" />' }),
 }))
 
+vi.mock('@/components/hermes/usage/UsagePricing.vue', () => ({
+  default: defineComponent({ name: 'UsagePricing', template: '<span />' }),
+}))
+
 import UsageView from '@/views/hermes/UsageView.vue'
 
 describe('UsageView period selector', () => {
diff --git a/tests/e2e/usage-cost.spec.ts b/tests/e2e/usage-cost.spec.ts
new file mode 100644
index 0000000000..33a2c0554f
--- /dev/null
+++ b/tests/e2e/usage-cost.spec.ts
@@ -0,0 +1,40 @@
+import { expect, test } from '@playwright/test'
+import { authenticate, mockHermesApi, TEST_ACCESS_KEY } from './fixtures'
+
+test('shows unknown, partial and free costs and saves explicit model pricing', async ({ page }) => {
+  await authenticate(page, TEST_ACCESS_KEY)
+  await mockHermesApi(page)
+  let coverage = { reported: 0, estimated: 0, unknown: 1 }
+  let cost = 0
+  const date = new Date().toISOString().slice(0, 10)
+  await page.route('**/api/studio/usage/stats?*', route => route.fulfill({ json: {
+    total_input_tokens: 10, total_output_tokens: 2, total_cache_read_tokens: 0, total_cache_write_tokens: 0, total_reasoning_tokens: 0,
+    total_sessions: 1, total_cost: cost, cost_coverage: coverage, model_usage: [], agent_usage: [],
+    daily_usage: [{ date, input_tokens: 10, output_tokens: 2, cache_read_tokens: 0, cache_write_tokens: 0, sessions: 1, errors: 0, cost, cost_coverage: coverage }],
+  } }))
+  let saved: any
+  await page.route('**/api/studio/usage/pricing', async route => {
+    if (route.request().method() === 'PUT') saved = route.request().postDataJSON()
+    await route.fulfill({ json: saved || { rates: [] } })
+  })
+  await page.goto('/#/hermes/usage')
+  const card = page.locator('.stat-card').filter({ hasText: 'Cost (USD)' })
+  await expect(card.getByText('Not recorded', { exact: true })).toBeVisible()
+  await expect(page.locator('tbody').getByText('Not recorded')).toBeVisible()
+  coverage = { reported: 1, estimated: 0, unknown: 1 }; cost = 0.25
+  await page.getByRole('button', { name: 'Refresh', exact: true }).click()
+  await expect(card.getByText('$0.25', { exact: true })).toBeVisible()
+  await expect(card.getByText('Partial cost; some usage is unpriced')).toBeVisible()
+  coverage = { reported: 1, estimated: 0, unknown: 0 }; cost = 0
+  await page.getByRole('button', { name: 'Refresh', exact: true }).click()
+  await expect(card.getByText('$0.00', { exact: true })).toBeVisible()
+  await page.getByRole('button', { name: 'Model pricing', exact: true }).click()
+  const dialog = page.getByRole('dialog')
+  await dialog.getByRole('button', { name: 'Add', exact: true }).click()
+  await dialog.getByRole('textbox', { name: 'Model ID', exact: true }).fill('test-model')
+  await dialog.getByRole('textbox', { name: 'Input', exact: true }).fill('2')
+  await dialog.getByRole('textbox', { name: 'Output', exact: true }).fill('8')
+  await dialog.getByRole('button', { name: 'Save', exact: true }).click()
+  await expect(dialog).toHaveCount(0)
+  expect(saved).toEqual({ rates: [{ provider: 'global', model: 'test-model', input: 2, output: 8 }] })
+})
diff --git a/tests/ekko-agent/model-request.test.ts b/tests/ekko-agent/model-request.test.ts
index 50f9cf5fd9..8e30dda7d9 100644
--- a/tests/ekko-agent/model-request.test.ts
+++ b/tests/ekko-agent/model-request.test.ts
@@ -31,6 +31,12 @@ const providerConfig: ModelProviderConfig = {
 }
 
 describe('ekko-agent model requests', () => {
+  it('preserves provider cost through chat and responses normalization', () => {
+    expect(normalizeOpenAIChatResponse('test', { choices: [], usage: { prompt_tokens: 10, completion_tokens: 2, cost: 0.002 } }).usage).toMatchObject({ costUsd: 0.002 })
+    expect(normalizeOpenAIResponsesResponse({ output: [], usage: { input_tokens: 10, output_tokens: 2, cost: 0 } }).usage).toMatchObject({ costUsd: 0 })
+    expect(normalizeOpenAIChatResponse('test', { choices: [], usage: { prompt_tokens: 10, completion_tokens: 2 } }).usage).not.toHaveProperty('costUsd')
+  })
+
   it('replays streamed DeepSeek reasoning_content through a complete tool loop', async () => {
     const encoder = new TextEncoder()
     let call = 0
@@ -1700,6 +1706,13 @@ describe('ekko-agent model requests', () => {
     })
   })
 
+  it('normalizes Gemini cached input and reasoning output for cost estimation', () => {
+    const response = normalizeGeminiResponse({ candidates: [], usageMetadata: {
+      promptTokenCount: 100, cachedContentTokenCount: 60, candidatesTokenCount: 10, thoughtsTokenCount: 20, totalTokenCount: 130,
+    } }, 'gemini-test')
+    expect(response.usage).toMatchObject({ inputTokens: 40, cacheReadTokens: 60, outputTokens: 30, reasoningTokens: 20, totalTokens: 130 })
+  })
+
   it('replays Gemini thought signatures with their original content parts', () => {
     const originalParts = [
       { text: 'I should call the tool.', thought: true },
diff --git a/tests/ekko-agent/runtime.test.ts b/tests/ekko-agent/runtime.test.ts
index 14e8a997ba..f4983a7897 100644
--- a/tests/ekko-agent/runtime.test.ts
+++ b/tests/ekko-agent/runtime.test.ts
@@ -729,6 +729,7 @@ describe('ekko-agent runtime', () => {
       content: 'Validation passed',
       finishReason: 'stop',
       usage: {
+        costUsd: 0.04,
         inputTokens: 12,
         outputTokens: 3,
         cacheReadTokens: 5,
@@ -745,6 +746,8 @@ describe('ekko-agent runtime', () => {
         background: true,
         summary: 'Validation passed',
         output: 'Validation passed',
+        costUsd: 0.04,
+        costSource: 'reported',
         childRunId: expect.any(String),
         apiCalls: 1,
         inputTokens: 12,
diff --git a/tests/server/native-agent-usage.test.ts b/tests/server/native-agent-usage.test.ts
index fcf3e01293..46dc298386 100644
--- a/tests/server/native-agent-usage.test.ts
+++ b/tests/server/native-agent-usage.test.ts
@@ -149,6 +149,13 @@ describe('global native usage accounting', () => {
       'claude-code': { inputTokens: 1203, outputTokens: 3, cacheReadTokens: 4160, apiCalls: 1 },
       grok: { inputTokens: 16950, outputTokens: 42, cacheReadTokens: 640, reasoningTokens: 37, apiCalls: 1 },
     }[agentId])
+    const costStats = getLocalUsageStats(sessionId, 1)
+    if (agentId === 'claude-code' || agentId === 'grok') {
+      expect(costStats.cost).toBeCloseTo(agentId === 'claude-code' ? 0.01027 : 0.00586024)
+      expect(costStats.cost_coverage).toEqual({ reported: 0, estimated: 1, unknown: 0 })
+    } else {
+      expect(costStats.cost_coverage?.unknown).toBe(1)
+    }
     await vi.waitFor(() => expect(emitted).toHaveBeenCalledWith(sessionId, 'usage.updated', expect.objectContaining({
       contextTokens: { codex: 17788, pi: 483, 'claude-code': 5366, grok: 17632 }[agentId],
     })))
@@ -156,11 +163,12 @@ describe('global native usage accounting', () => {
 
   it.each(['pi', 'claude-code', 'grok', 'codex'] as const)('%s scoped usage still comes only from the proxy', async agentId => {
     start(agentId, 'scoped')
-    manager.handleProxyUsageEvent(sessionId, { type: 'response.completed', data: { response: { id: 'proxy-1', model: 'proxy-model', usage: { input_tokens: 12, output_tokens: 3 } } } })
+    manager.handleProxyUsageEvent(sessionId, { type: 'response.completed', data: { response: { id: 'proxy-1', model: 'proxy-model', usage: { input_tokens: 12, output_tokens: 3, cost: 0.001 } } } })
     for (const event of fixtures[agentId]) emit(event)
     close()
     expect(getRecordedUsageTotals(sessionId, 'coding_agent')).toMatchObject({ inputTokens: 12, outputTokens: 3, apiCalls: 1 })
     expect(getUsage(sessionId)?.model).toBe('proxy-model')
+    expect(getLocalUsageStats(sessionId, 1)).toMatchObject({ cost: 0.001, cost_coverage: { reported: 1, estimated: 0, unknown: 0 } })
   })
 
   it('does not duplicate Pi messages repeated in delivery or terminal events, and resets for another turn', () => {
diff --git a/tests/server/sessions-controller.test.ts b/tests/server/sessions-controller.test.ts
index 15a44ccfd6..6abe8e0bfd 100644
--- a/tests/server/sessions-controller.test.ts
+++ b/tests/server/sessions-controller.test.ts
@@ -137,6 +137,7 @@ vi.mock('../../packages/server/src/modules/studio/repositories/usage-store', ()
   getUsage: vi.fn(),
   getUsageBatch: vi.fn(),
   getLocalUsageStats: getLocalUsageStatsMock,
+  getUnpricedHermesUsageSessions: vi.fn(() => []),
   getRecordedUsageSessionIds: getRecordedUsageSessionIdsMock,
 }))
 
@@ -1972,7 +1973,7 @@ describe('session conversations controller', () => {
 
     expect(getLocalUsageStatsMock).toHaveBeenCalledWith('default', 2)
     expect(getRecordedUsageSessionIdsMock).toHaveBeenCalledWith('default')
-    expect(getUsageStatsFromDbMock).toHaveBeenCalledWith(2, undefined, 'default', ['local-session'])
+    expect(getUsageStatsFromDbMock).toHaveBeenCalledWith(2, undefined, 'default', ['local-session'], [])
     expect(ctx.body).toMatchObject({
       total_input_tokens: 30,
       total_output_tokens: 15,
@@ -2024,7 +2025,7 @@ describe('session conversations controller', () => {
 
     expect(getLocalUsageStatsMock).toHaveBeenCalledWith('research', 2)
     expect(getRecordedUsageSessionIdsMock).toHaveBeenCalledWith('research')
-    expect(getUsageStatsFromDbMock).toHaveBeenCalledWith(2, undefined, 'research', [])
+    expect(getUsageStatsFromDbMock).toHaveBeenCalledWith(2, undefined, 'research', [], [])
     expect(ctx.body).toMatchObject({
       total_input_tokens: 12,
       total_output_tokens: 6,
diff --git a/tests/server/sessions-routes.test.ts b/tests/server/sessions-routes.test.ts
index da05c15068..fb33afae11 100644
--- a/tests/server/sessions-routes.test.ts
+++ b/tests/server/sessions-routes.test.ts
@@ -82,6 +82,8 @@ vi.mock('../../packages/server/src/modules/studio/controllers/sessions', () => (
   usageBatch: usageBatchMock,
   usageSingle: usageSingleMock,
   usageStats: usageStatsMock,
+  usagePricing: vi.fn(),
+  updateUsagePricing: vi.fn(),
   contextLength: contextLengthMock,
   exportSession: exportSessionMock,
   listWorkspaceRunChanges: listWorkspaceRunChangesMock,
diff --git a/tests/server/usage-analytics-db.test.ts b/tests/server/usage-analytics-db.test.ts
index cde905af6a..15892cde8b 100644
--- a/tests/server/usage-analytics-db.test.ts
+++ b/tests/server/usage-analytics-db.test.ts
@@ -213,6 +213,7 @@ describe('native-style Hermes usage analytics DB aggregation', () => {
       sessions: 1,
       errors: 0,
       cost: 0.005,
+      cost_coverage: { reported: 0, estimated: 1, unknown: 0 },
     })
     expect(result.by_day[1]).toMatchObject({
       date: day(now),
@@ -267,4 +268,20 @@ describe('native-style Hermes usage analytics DB aggregation', () => {
     expect(result.output_tokens).toBe(6)
     expect(result.total_api_calls).toBe(0)
   })
+  it('recovers excluded session costs separately and treats legacy default zero as unknown', async () => {
+    const now = 1_700_000_000
+    profileDir = createStateDb(true)
+    profileMock.getActiveProfileDir.mockReturnValue(profileDir)
+    insertSession(profileDir, { id: 'local', started_at: now - 10, input_tokens: 100, estimated_cost_usd: 0.12 })
+    insertSession(profileDir, { id: 'unknown', started_at: now - 10, input_tokens: 10 })
+    insertSession(profileDir, { id: 'free', started_at: now - 10, input_tokens: 20, actual_cost_usd: 0 })
+    const mod = await import('../../packages/server/src/modules/hermes/services/history/sessions-db')
+    const result = await mod.getUsageStatsFromDb(1, now, undefined, ['local'], ['local'])
+    expect(result.input_tokens).toBe(30)
+    expect(result.cost).toBe(0)
+    expect(result.cost_coverage).toEqual({ reported: 1, estimated: 0, unknown: 1 })
+    expect(result.cost_fallbacks).toEqual([{ session_id: 'local', date: day(now), cost: 0.12, source: 'estimated' }])
+    expect((await mod.getUsageStatsFromDb(1, now, undefined, ['local'])).cost_fallbacks).toEqual([])
+  })
+
 })
diff --git a/tests/server/usage-cost.test.ts b/tests/server/usage-cost.test.ts
new file mode 100644
index 0000000000..9c66391431
--- /dev/null
+++ b/tests/server/usage-cost.test.ts
@@ -0,0 +1,116 @@
+import { DatabaseSync } from 'node:sqlite'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { normalizeUsageCost, estimateUsageCost } from '../../packages/server/src/modules/studio/services/usage/usage-cost'
+import { applyHermesCostFallbacks } from '../../packages/server/src/modules/studio/services/usage/hermes-cost-fallback'
+import { NativeTurnUsage } from '../../packages/server/src/modules/coding-agents/services/runtime/native-usage'
+import { USAGE_SCHEMA, USAGE_RUN_INDEX, USAGE_PRICING_SCHEMA } from '../../packages/server/src/modules/studio/infrastructure/database/schemas'
+import { recordSessionUsage } from '../../packages/server/src/modules/studio/services/usage/usage-recorder'
+import { getLocalUsageStats, getUnpricedHermesUsageSessions } from '../../packages/server/src/modules/studio/repositories/usage-store'
+import { getUsagePricing, saveUsagePricing, validateUsagePricing } from '../../packages/server/src/modules/studio/services/usage/usage-pricing'
+
+let db: DatabaseSync
+vi.mock('../../packages/server/src/modules/studio/infrastructure/database/index', () => ({
+  isSqliteAvailable: () => true, getDb: () => db,
+  jsonGet: vi.fn(), jsonSet: vi.fn(), jsonGetAll: vi.fn(), jsonDelete: vi.fn(),
+}))
+
+describe('usage cost accounting', () => {
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:')
+    db.exec(`CREATE TABLE session_usage (${Object.entries(USAGE_SCHEMA).map(([key, sql]) => `${key} ${sql}`).join(',')}); ${USAGE_RUN_INDEX};
+      CREATE TABLE usage_pricing (${Object.entries(USAGE_PRICING_SCHEMA).map(([key, sql]) => `${key} ${sql}`).join(',')});`)
+  })
+  afterEach(() => db.close())
+  function record(runId: string, usage: unknown, extra: Record<string, any> = {}) {
+    recordSessionUsage({ sessionId: 'session', source: 'coding_agent', agent: 'codex', runId, profile: 'p', provider: 'global', model: 'test-model', usage, ...extra })
+  }
+
+  it('retains explicit free usage and rejects invalid costs', () => {
+    expect(normalizeUsageCost({ usage: { cost: 0 } })).toEqual({ costUsd: 0, costSource: 'reported' })
+    expect(normalizeUsageCost({ response: { usage: { cost: '0.12345' } } })).toEqual({ costUsd: 0.12345, costSource: 'reported' })
+    expect(normalizeUsageCost({ cost: { total: 0 } }, 'estimated')).toBeUndefined()
+    expect(normalizeUsageCost({ estimated_cost_usd: 1, actual_cost_usd: 0 })).toEqual({ costUsd: 0, costSource: 'reported' })
+    for (const cost of [null, undefined, false, true, '', ' ', -1, Infinity, NaN, {}, []]) expect(normalizeUsageCost({ cost })).toBeUndefined()
+  })
+
+  it('persists fractional USD once per call and distinguishes unknown from free', () => {
+    const usage = { input_tokens: 100, output_tokens: 10 }
+    record('paid', { ...usage, cost: 0.00234 })
+    record('paid', { ...usage, cost: 0.00234 })
+    record('free', { ...usage, cost: 0 })
+    record('unknown', usage)
+    const stats = getLocalUsageStats('p', 30)
+    expect(stats.cost).toBeCloseTo(0.00234)
+    expect(stats.input_tokens).toBe(300)
+    expect(stats.cost_coverage).toEqual({ reported: 2, estimated: 0, unknown: 1 })
+    expect(stats.by_day[0].cost).toBeCloseTo(stats.cost)
+    expect(stats.by_day[0].cost_coverage).toEqual(stats.cost_coverage)
+    expect(getLocalUsageStats('other', 30).cost).toBe(0)
+  })
+
+  it('estimates disjoint input/output/cache tokens using saved prices without repricing history', () => {
+    const price = { provider: 'global', model: 'test-model', input: 2, output: 8, cacheRead: 0.2, cacheWrite: 2.5 }
+    saveUsagePricing('p', [price])
+    const usage = { inputTokens: 1000, outputTokens: 200, reasoningTokens: 100, cacheReadTokens: 5000, cacheWriteTokens: 100 }
+    record('estimate', usage)
+    expect(getLocalUsageStats('p', 1)).toMatchObject({ cost: 0.00485, cost_coverage: { reported: 0, estimated: 1, unknown: 0 } })
+    saveUsagePricing('p', [{ ...price, input: 99 }])
+    record('reported', { ...usage, cost: 0 })
+    expect(getLocalUsageStats('p', 1).cost).toBeCloseTo(0.00485)
+    expect(estimateUsageCost(usage, { ...price, cacheRead: undefined })).toBeUndefined()
+    record('other-profile', usage, { profile: 'other' })
+    expect(getLocalUsageStats('other', 1).cost_coverage?.unknown).toBe(1)
+    expect(getUsagePricing('p')[0].input).toBe(99)
+    expect(getUsagePricing('other')).toEqual([])
+  })
+
+  it('only permits exact, unique, finite, non-negative model pricing', () => {
+    const row = { provider: ' global ', model: ' m ', input: 1, output: 0, cacheRead: null }
+    expect(validateUsagePricing([row])).toEqual([{ provider: 'global', model: 'm', input: 1, output: 0 }])
+    for (const input of [-1, NaN, Infinity, '1', null]) expect(() => validateUsagePricing([{ ...row, input }])).toThrow()
+    expect(() => validateUsagePricing([row, row])).toThrow()
+    expect(() => validateUsagePricing([{ ...row, provider: '' }])).toThrow()
+  })
+
+  it('supplements unpriced Hermes sessions once while preserving token totals', () => {
+    const usage = { inputTokens: 10, outputTokens: 2 }
+    record('one', usage, { source: 'hermes', agent: 'hermes' })
+    record('two', usage, { source: 'hermes', agent: 'hermes' })
+    const candidates = getUnpricedHermesUsageSessions('p', 1)
+    expect(candidates).toHaveLength(1)
+    const stats = getLocalUsageStats('p', 1)
+    const fallback = { session_id: 'session', date: candidates[0].days[0].date, cost: 0.25, source: 'estimated' as const }
+    applyHermesCostFallbacks(stats, candidates, [fallback, fallback])
+    expect(stats).toMatchObject({ cost: 0.25, input_tokens: 20, output_tokens: 4, sessions: 1, cost_coverage: { reported: 0, estimated: 1, unknown: 0 } })
+    expect(stats.by_day[0]).toMatchObject({ cost: 0.25, cost_coverage: { reported: 0, estimated: 1, unknown: 0 } })
+    record('known', { ...usage, cost: 0 }, { source: 'hermes', agent: 'hermes' })
+    expect(getUnpricedHermesUsageSessions('p', 1)).toEqual([])
+  })
+
+  it('does not apply cumulative Hermes costs to sessions extending beyond the period', () => {
+    record('old', { input_tokens: 10, output_tokens: 2 }, { source: 'hermes', agent: 'hermes' })
+    db.prepare('UPDATE session_usage SET created_at = ?').run(Date.now() - 3 * 86_400_000)
+    record('new', { input_tokens: 10, output_tokens: 2 }, { source: 'hermes', agent: 'hermes' })
+    expect(getUnpricedHermesUsageSessions('p', 1)).toEqual([])
+  })
+
+  it('keeps native model costs and authoritative Claude run totals without double counting', () => {
+    const native = new NativeTurnUsage()
+    native.observeClaude({ type: 'result', usage: { input_tokens: 100, output_tokens: 10 }, total_cost_usd: 0.25,
+      modelUsage: { a: { inputTokens: 100, outputTokens: 10, costUSD: 0.3 } } })
+    expect(native.rows('claude-code', undefined)).toMatchObject([{ usage: { inputTokens: 100 }, cost: { costUsd: 0.25, costSource: 'estimated' } }])
+    const pi = new NativeTurnUsage()
+    const event = { type: 'message_end', message: { id: 'x', role: 'assistant', model: 'm', usage: { input: 10, output: 2, cost: { total: 0.02 } } } }
+    expect(pi.observePi(event)?.cost).toEqual({ costUsd: 0.02, costSource: 'estimated' })
+    expect(pi.observePi(event)).toBeUndefined()
+  })
+  it('retains known Grok response costs when the terminal event omits totals', () => {
+    const tracker = new NativeTurnUsage()
+    tracker.observeGrok({ type: 'usage', messageId: 'one', usage: { input_tokens: 10, output_tokens: 2, cost: 0.03 } })
+    tracker.observeGrok({ type: 'usage', messageId: 'one', usage: { input_tokens: 10, output_tokens: 2, cost: 0.03 } })
+    tracker.observeGrok({ type: 'usage', messageId: 'two', usage: { input_tokens: 20, output_tokens: 3, cost: 0.04 } })
+    tracker.observeGrok({ type: 'error' })
+    expect(tracker.rows('grok', undefined)).toMatchObject([{ usage: { inputTokens: 30 }, cost: { costUsd: 0.07, costSource: 'estimated' } }])
+  })
+
+})
diff --git a/tests/server/usage-store-agent-stats-db.test.ts b/tests/server/usage-store-agent-stats-db.test.ts
index cbdd7fa593..fc859c4f45 100644
--- a/tests/server/usage-store-agent-stats-db.test.ts
+++ b/tests/server/usage-store-agent-stats-db.test.ts
@@ -26,6 +26,8 @@ describe('usage store agent breakdown', () => {
         cache_read_tokens INTEGER NOT NULL DEFAULT 0,
         cache_write_tokens INTEGER NOT NULL DEFAULT 0,
         reasoning_tokens INTEGER NOT NULL DEFAULT 0,
+        cost_usd REAL,
+        cost_source TEXT NOT NULL DEFAULT 'unknown',
         api_calls INTEGER NOT NULL DEFAULT 0,
         model TEXT NOT NULL DEFAULT '',
         profile TEXT NOT NULL DEFAULT 'default',
diff --git a/tests/server/usage-store.test.ts b/tests/server/usage-store.test.ts
index bad839d833..f69bd9c00a 100644
--- a/tests/server/usage-store.test.ts
+++ b/tests/server/usage-store.test.ts
@@ -187,6 +187,8 @@ describe('Usage Store (SQLite path)', () => {
       'default', // profile
       0, // isEstimated
       expect.any(Number), // created_at
+      null, // costUsd
+      'unknown', // costSource
     )
   })
 
@@ -217,6 +219,8 @@ describe('Usage Store (SQLite path)', () => {
       'default', // profile
       0, // isEstimated
       expect.any(Number), // created_at
+      null, // costUsd
+      'unknown', // costSource
       expect.any(Number), // updated_at
     )
   })
@@ -307,9 +311,10 @@ describe('Usage Store (SQLite path)', () => {
         { agent: 'coding_agent', input_tokens: 100, output_tokens: 40, cache_read_tokens: 30, cache_write_tokens: 5, reasoning_tokens: 8, sessions: 2 },
       ],
       by_day: [
-        { date: '2026-07-11', input_tokens: 100, output_tokens: 40, cache_read_tokens: 30, cache_write_tokens: 5, sessions: 2, errors: 0, cost: 0 },
+        { date: '2026-07-11', input_tokens: 100, output_tokens: 40, cache_read_tokens: 30, cache_write_tokens: 5, sessions: 2, errors: 0, cost: 0, cost_coverage: { reported: 0, estimated: 0, unknown: 0 } },
       ],
       cost: 0,
+      cost_coverage: { reported: 0, estimated: 0, unknown: 0 },
       total_api_calls: 3,
     })
     expect(getRecordedUsageSessionIds('default')).toEqual(['session-1', 'session-2'])

From a9ba68ca9895f55e1a51f1e8b9831d00d95f850e Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Tue, 29 Sep 2026 22:00:15 +0800
Subject: [PATCH 2/8] use local model catalog for context limits and usage
 costs

---
 docs/harness/server-module-boundaries.md      |   1 +
 docs/harness/usage-cost.md                    |  43 +++++-
 packages/client/src/i18n/locales/ar.ts        |   2 +-
 packages/client/src/i18n/locales/de.ts        |   2 +-
 packages/client/src/i18n/locales/en.ts        |   2 +-
 packages/client/src/i18n/locales/es.ts        |   2 +-
 packages/client/src/i18n/locales/fr.ts        |   2 +-
 packages/client/src/i18n/locales/ja.ts        |   2 +-
 packages/client/src/i18n/locales/ko.ts        |   2 +-
 packages/client/src/i18n/locales/pt.ts        |   2 +-
 packages/client/src/i18n/locales/ru.ts        |   2 +-
 packages/client/src/i18n/locales/zh-TW.ts     |   2 +-
 packages/client/src/i18n/locales/zh.ts        |   2 +-
 packages/server/src/bootstrap/http.ts         |   3 +
 .../modules/hermes/services/models/context.ts |  36 +----
 .../studio/infrastructure/database/schemas.ts |   1 +
 .../modules/studio/public/model-catalog.ts    |   2 +
 .../studio/repositories/usage-store.ts        |  34 ++++-
 .../studio/services/models/model-catalog.ts   | 125 +++++++++++++++++
 .../studio/services/usage/catalog-pricing.ts  |  71 ++++++++++
 .../studio/services/usage/usage-cost.ts       |  19 ++-
 .../studio/services/usage/usage-recorder.ts   |  23 +++-
 tests/server/model-catalog.test.ts            | 127 ++++++++++++++++++
 tests/server/model-context.test.ts            |  25 +++-
 tests/server/usage-cost.test.ts               |  62 ++++++++-
 tests/server/usage-store.test.ts              |  18 +++
 26 files changed, 555 insertions(+), 57 deletions(-)
 create mode 100644 packages/server/src/modules/studio/public/model-catalog.ts
 create mode 100644 packages/server/src/modules/studio/services/models/model-catalog.ts
 create mode 100644 packages/server/src/modules/studio/services/usage/catalog-pricing.ts
 create mode 100644 tests/server/model-catalog.test.ts

diff --git a/docs/harness/server-module-boundaries.md b/docs/harness/server-module-boundaries.md
index 26bc9872e9..34fca0495b 100644
--- a/docs/harness/server-module-boundaries.md
+++ b/docs/harness/server-module-boundaries.md
@@ -69,6 +69,7 @@ packages/server/src/
         runs.ts
         sessions.ts
         usage.ts
+        model-catalog.ts           # shared local models.dev metadata and startup refresh
         workspace.ts
         workspace-files.ts          # shared path, preview, Git status, and file policy facade
         group-chat-agent-runtime.ts # injected concrete Agent adapters for Group Chat
diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index 1529351c27..22acc56fe6 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -15,8 +15,41 @@ million ordinary input, output, cache read and cache write tokens. Provider and
 model IDs must match exactly; no cross-provider model-name fallback is used.
 Native runs without provider metadata use `global`. Missing cache rates leave
 cached usage unpriced. Reasoning is already included in output tokens. Reported
-cost wins over configured rates. Prices apply at recording time, so price edits
-do not reprice historical rows or duplicate run IDs.
+cost wins over configured rates, which win over models.dev rates. A partial
+manual price does not borrow missing rates from the catalog. Prices apply at
+recording time, so price edits do not reprice historical rows or duplicate run IDs.
+
+## Shared models.dev catalog
+
+Studio downloads `https://models.dev/api.json` once on each server startup, in
+the background, to `config.appHome/models/models.dev.json`. This is Web UI
+state (default `~/.hermes-web-ui`), separate from Hermes Agent's own cache.
+Context matching, output limits, model capabilities and cost estimates share
+the same in-memory snapshot, loaded from disk before the download completes.
+Manual context overrides and existing configuration remain higher priority.
+
+Downloads have a 15-second timeout and a 20 MiB limit. JSON/provider/model
+validation runs before atomic replacement; HTTP, network, malformed response
+and disk errors preserve the last good snapshot. Concurrent callers share one
+download; cold-start cost recording can retry after a five-minute cooldown.
+No cache plus no network preserves the existing context fallback and unknown
+costs. The first successful download fills only new records awaiting that
+download, without duplicating tokens or resurrecting deleted rows.
+
+Automatic pricing requires the exact provider/model pair (or a known provider
+alias). Unknown custom relays do not inherit official model prices. Catalog
+prices are reference estimates, not a relay invoice, subscription charge or
+account-specific discount; configure custom rates when appropriate. Missing
+rates for used token categories leave cost unknown. Context tiers include cache
+tokens; a run aggregate above a tier threshold stays unknown unless it represents
+a single API call. Explicit tiers take precedence over legacy `context_over_200k`.
+Separate reasoning rates replace the reasoning portion of the output charge.
+
+Estimated records retain nullable `cost_pricing` JSON with the rate source,
+effective USD-per-million rates, catalog SHA-256 version, download time and
+selected context threshold. `cost_source` remains `estimated`, so existing
+Studio/App coverage and total-cost displays work without a new API contract.
+Catalog refreshes never reprice previously stored records.
 
 Hermes token deduplication and cost recovery are separate. A native session bill
 can supplement a local session only if all its local rows are unpriced and the
@@ -24,5 +57,7 @@ whole session falls inside the period. It cannot be added to a partly priced
 session. Native aggregate costs retain Hermes's session-start date; for sessions
 spanning days, daily coverage stays unknown where charges cannot be attributed.
 
-Validation: `usage-cost.test.ts`, `usage-analytics-db.test.ts`, native usage and
-model adapter tests, and `tests/e2e/usage-cost.spec.ts` cover accounting and UI.
+Validation: `model-catalog.test.ts`, `model-context.test.ts`, `usage-cost.test.ts`,
+`usage-store.test.ts`, `usage-analytics-db.test.ts`, native usage/model adapter
+tests and `tests/e2e/usage-cost.spec.ts` cover refresh/offline behavior, shared
+context limits, persistence, precedence, deduplication and UI.
diff --git a/packages/client/src/i18n/locales/ar.ts b/packages/client/src/i18n/locales/ar.ts
index e7013b78e3..267836b336 100644
--- a/packages/client/src/i18n/locales/ar.ts
+++ b/packages/client/src/i18n/locales/ar.ts
@@ -3541,7 +3541,7 @@ export default {
     },
     pricing: {
       title: "أسعار النماذج",
-      help: "دولار لكل مليون رمز. يجب تطابق معرفَي المزود والنموذج تمامًا (مثل global). يُستخدم التقدير عند غياب التكلفة فقط. سعر التخزين المؤقت الفارغ يعني أنه غير معروف. تسري التغييرات على الاستدعاءات القادمة دون إعادة حساب السجل.",
+      help: "عند عدم تعيين سعر مخصص، تُقدَّر التكلفة باستخدام أسعار النموذج المطابق في models.dev. دولار لكل مليون رمز. يجب تطابق معرفَي المزود والنموذج تمامًا (مثل global). يُستخدم التقدير عند غياب التكلفة فقط. سعر التخزين المؤقت الفارغ يعني أنه غير معروف. تسري التغييرات على الاستدعاءات القادمة دون إعادة حساب السجل.",
       provider: "معرف المزود",
       model: "معرف النموذج",
       input: "الإدخال",
diff --git a/packages/client/src/i18n/locales/de.ts b/packages/client/src/i18n/locales/de.ts
index e4bb509db4..6c22dbb2d6 100644
--- a/packages/client/src/i18n/locales/de.ts
+++ b/packages/client/src/i18n/locales/de.ts
@@ -2817,7 +2817,7 @@ jobTriggered: 'Job ausgelost',
     },
     pricing: {
       title: "Modellpreise",
-      help: "USD pro Million Tokens. Anbieter- und Modell-ID müssen genau passen (z. B. global). Schätzung nur ohne gemeldete Kosten. Leere Cachepreise bedeuten unbekannt. Änderungen gelten für künftige Aufrufe; frühere Kosten werden nicht neu berechnet.",
+      help: "Ohne eigene Preise werden passende Modelle anhand von models.dev geschätzt. USD pro Million Tokens. Anbieter- und Modell-ID müssen genau passen (z. B. global). Schätzung nur ohne gemeldete Kosten. Leere Cachepreise bedeuten unbekannt. Änderungen gelten für künftige Aufrufe; frühere Kosten werden nicht neu berechnet.",
       provider: "Anbieter-ID",
       model: "Modell-ID",
       input: "Eingabe",
diff --git a/packages/client/src/i18n/locales/en.ts b/packages/client/src/i18n/locales/en.ts
index 6c24fbfc47..dc8837461e 100644
--- a/packages/client/src/i18n/locales/en.ts
+++ b/packages/client/src/i18n/locales/en.ts
@@ -3560,7 +3560,7 @@ export default {
     },
     pricing: {
       title: "Model pricing",
-      help: "USD per million tokens. Match provider and model IDs exactly (e.g. global). Used only when no cost is returned. Blank cache rates mean unknown. Changes apply to future calls; historical costs are not recalculated.",
+      help: "Without a custom price, models.dev is used to estimate costs for matching models. USD per million tokens. Match provider and model IDs exactly (e.g. global). Used only when no cost is returned. Blank cache rates mean unknown. Changes apply to future calls; historical costs are not recalculated.",
       provider: "Provider ID",
       model: "Model ID",
       input: "Input",
diff --git a/packages/client/src/i18n/locales/es.ts b/packages/client/src/i18n/locales/es.ts
index 5c7176c1a7..0a232427c5 100644
--- a/packages/client/src/i18n/locales/es.ts
+++ b/packages/client/src/i18n/locales/es.ts
@@ -2817,7 +2817,7 @@ jobTriggered: 'Job ejecutado',
     },
     pricing: {
       title: "Precios de modelos",
-      help: "USD por millón de tokens. Coincidencia exacta de ID de proveedor y modelo (p. ej. global). Solo se estima si no se recibe un coste. Caché sin precio significa desconocido. Cambios para futuras llamadas, sin recalcular el historial.",
+      help: "Sin precios personalizados, se estima el coste con los precios del modelo correspondiente en models.dev. USD por millón de tokens. Coincidencia exacta de ID de proveedor y modelo (p. ej. global). Solo se estima si no se recibe un coste. Caché sin precio significa desconocido. Cambios para futuras llamadas, sin recalcular el historial.",
       provider: "ID del proveedor",
       model: "ID del modelo",
       input: "Entrada",
diff --git a/packages/client/src/i18n/locales/fr.ts b/packages/client/src/i18n/locales/fr.ts
index 94e5bf861d..2e63c7e539 100644
--- a/packages/client/src/i18n/locales/fr.ts
+++ b/packages/client/src/i18n/locales/fr.ts
@@ -2817,7 +2817,7 @@ jobTriggered: 'Job declenche',
     },
     pricing: {
       title: "Tarifs des modèles",
-      help: "USD par million de tokens. Identifiants fournisseur et modèle exacts (par ex. global). Estimation uniquement si aucun coût reçu. Cache sans tarif : coût inconnu. Modifications pour les prochains appels, sans recalcul du passé.",
+      help: "Sans tarif personnalisé, le coût est estimé avec les tarifs du modèle correspondant sur models.dev. USD par million de tokens. Identifiants fournisseur et modèle exacts (par ex. global). Estimation uniquement si aucun coût reçu. Cache sans tarif : coût inconnu. Modifications pour les prochains appels, sans recalcul du passé.",
       provider: "ID fournisseur",
       model: "ID modèle",
       input: "Entrée",
diff --git a/packages/client/src/i18n/locales/ja.ts b/packages/client/src/i18n/locales/ja.ts
index 561fb95e0f..bcc6a7484a 100644
--- a/packages/client/src/i18n/locales/ja.ts
+++ b/packages/client/src/i18n/locales/ja.ts
@@ -2816,7 +2816,7 @@ export default {
     },
     pricing: {
       title: "モデル料金",
-      help: "100万トークンあたりの米ドル。プロバイダーとモデルの ID を完全一致で指定（例: global）。費用が返されない場合のみ推定します。キャッシュ料金の空欄は不明を意味します。変更は今後の呼び出しに適用され、過去の費用は再計算されません。",
+      help: "カスタム料金が未設定の場合、一致するモデルの models.dev 料金で推定します。100万トークンあたりの米ドル。プロバイダーとモデルの ID を完全一致で指定（例: global）。費用が返されない場合のみ推定します。キャッシュ料金の空欄は不明を意味します。変更は今後の呼び出しに適用され、過去の費用は再計算されません。",
       provider: "プロバイダー ID",
       model: "モデル ID",
       input: "入力",
diff --git a/packages/client/src/i18n/locales/ko.ts b/packages/client/src/i18n/locales/ko.ts
index ead44db086..1cecfa1258 100644
--- a/packages/client/src/i18n/locales/ko.ts
+++ b/packages/client/src/i18n/locales/ko.ts
@@ -2816,7 +2816,7 @@ export default {
     },
     pricing: {
       title: "모델 단가",
-      help: "백만 토큰당 USD입니다. 공급자와 모델 ID를 정확히 일치시키세요(예: global). 비용이 반환되지 않을 때만 추정합니다. 캐시 단가가 비어 있으면 알 수 없음입니다. 이후 호출부터 적용되며 과거 비용은 다시 계산하지 않습니다.",
+      help: "사용자 지정 단가가 없으면 models.dev에서 일치하는 모델의 가격으로 비용을 추정합니다. 백만 토큰당 USD입니다. 공급자와 모델 ID를 정확히 일치시키세요(예: global). 비용이 반환되지 않을 때만 추정합니다. 캐시 단가가 비어 있으면 알 수 없음입니다. 이후 호출부터 적용되며 과거 비용은 다시 계산하지 않습니다.",
       provider: "공급자 ID",
       model: "모델 ID",
       input: "입력",
diff --git a/packages/client/src/i18n/locales/pt.ts b/packages/client/src/i18n/locales/pt.ts
index c537ea636a..6bbac15119 100644
--- a/packages/client/src/i18n/locales/pt.ts
+++ b/packages/client/src/i18n/locales/pt.ts
@@ -2817,7 +2817,7 @@ jobTriggered: 'Job acionado',
     },
     pricing: {
       title: "Preços dos modelos",
-      help: "USD por milhão de tokens. IDs de provedor e modelo devem corresponder exatamente (ex.: global). Estimativa apenas sem custo informado. Cache sem preço significa desconhecido. Alterações valem para futuras chamadas, sem recalcular o histórico.",
+      help: "Sem preços personalizados, o custo é estimado com os preços do modelo correspondente no models.dev. USD por milhão de tokens. IDs de provedor e modelo devem corresponder exatamente (ex.: global). Estimativa apenas sem custo informado. Cache sem preço significa desconhecido. Alterações valem para futuras chamadas, sem recalcular o histórico.",
       provider: "ID do provedor",
       model: "ID do modelo",
       input: "Entrada",
diff --git a/packages/client/src/i18n/locales/ru.ts b/packages/client/src/i18n/locales/ru.ts
index 9e91118cdc..0fcdcf7c51 100644
--- a/packages/client/src/i18n/locales/ru.ts
+++ b/packages/client/src/i18n/locales/ru.ts
@@ -3196,7 +3196,7 @@ export default {
     },
     pricing: {
       title: "Тарифы моделей",
-      help: "USD за миллион токенов. ID провайдера и модели должны совпадать точно (например global). Оценка применяется, если стоимость не получена. Пустой тариф кеша означает неизвестную стоимость. Изменения действуют для будущих вызовов без пересчёта истории.",
+      help: "Если свой тариф не задан, стоимость оценивается по тарифам соответствующей модели из models.dev. USD за миллион токенов. ID провайдера и модели должны совпадать точно (например global). Оценка применяется, если стоимость не получена. Пустой тариф кеша означает неизвестную стоимость. Изменения действуют для будущих вызовов без пересчёта истории.",
       provider: "ID провайдера",
       model: "ID модели",
       input: "Ввод",
diff --git a/packages/client/src/i18n/locales/zh-TW.ts b/packages/client/src/i18n/locales/zh-TW.ts
index 44c87f9341..b7e948ffde 100644
--- a/packages/client/src/i18n/locales/zh-TW.ts
+++ b/packages/client/src/i18n/locales/zh-TW.ts
@@ -3502,7 +3502,7 @@ export default {
     },
     pricing: {
       title: "模型單價",
-      help: "單位為美元／百萬 Token。依供應商和模型 ID 精確匹配（例如 global），僅在上游未回傳費用時估算。快取單價留空表示未知。修改從後續呼叫生效，不重算歷史費用。",
+      help: "未設定自訂單價時，自動使用 models.dev 中相符模型的價格估算。單位為美元／百萬 Token。依供應商和模型 ID 精確匹配（例如 global），僅在上游未回傳費用時估算。快取單價留空表示未知。修改從後續呼叫生效，不重算歷史費用。",
       provider: "供應商 ID",
       model: "模型 ID",
       input: "輸入",
diff --git a/packages/client/src/i18n/locales/zh.ts b/packages/client/src/i18n/locales/zh.ts
index 0afcb8f832..80eb964d8d 100644
--- a/packages/client/src/i18n/locales/zh.ts
+++ b/packages/client/src/i18n/locales/zh.ts
@@ -3608,7 +3608,7 @@ export default {
     },
     pricing: {
       title: "模型单价",
-      help: "单位为美元／百万 Token。按供应商和模型 ID 精确匹配（例如 global），仅在上游未返回费用时估算。缓存单价留空表示未知。修改从后续调用生效，不重算历史费用。",
+      help: "未设置自定义单价时，自动使用 models.dev 中匹配模型的价格估算。单位为美元／百万 Token。按供应商和模型 ID 精确匹配（例如 global），仅在上游未返回费用时估算。缓存单价留空表示未知。修改从后续调用生效，不重算历史费用。",
       provider: "供应商 ID",
       model: "模型 ID",
       input: "输入",
diff --git a/packages/server/src/bootstrap/http.ts b/packages/server/src/bootstrap/http.ts
index b023b62441..bf353a2221 100644
--- a/packages/server/src/bootstrap/http.ts
+++ b/packages/server/src/bootstrap/http.ts
@@ -33,6 +33,7 @@ import { injectBundledMcpServer } from '../modules/hermes/services/mcp/studio-au
 import { ensureProfileGatewaysRunning } from '../modules/hermes/services/gateway/autostart'
 import { runRegisteredStartupTasks } from './startup-tasks'
 import { refreshConfiguredProviderModelCatalogsInBackground } from '../modules/hermes/services/providers/model-catalog-cache'
+import { refreshModelCatalog } from '../modules/studio/public/model-catalog'
 import { initializeOpenCodeFreeInBackground } from '../modules/hermes/services/providers/opencode-free'
 import {
   scanLanDevices,
@@ -498,6 +499,8 @@ export async function bootstrap() {
   // Initialize all web-ui SQLite tables
   const { initAllStores } = await import('../modules/studio/infrastructure/database/init')
   initAllStores()
+  // Refresh once on every startup; context and cost lookups can use the disk cache immediately.
+  void refreshModelCatalog(true)
   const { interruptOrphanedTaskPlans } = await import('../modules/studio/repositories/task-plan-store')
   interruptOrphanedTaskPlans()
   startChatWebhookDispatcher()
diff --git a/packages/server/src/modules/hermes/services/models/context.ts b/packages/server/src/modules/hermes/services/models/context.ts
index f91693ca42..505d933bc2 100644
--- a/packages/server/src/modules/hermes/services/models/context.ts
+++ b/packages/server/src/modules/hermes/services/models/context.ts
@@ -1,13 +1,13 @@
-import { resolve, join } from 'path'
-import { readFileSync, existsSync, statSync } from 'fs'
+import { join } from 'path'
+import { readFileSync, existsSync } from 'fs'
 import yaml from 'js-yaml'
 import { getCompatibleCustomProviders } from '../../../studio/contracts/provider-compat'
 import { PROVIDER_PRESETS } from '../../../studio/contracts/providers'
 import { readModelContextRecord } from '../../../studio/public/provider-context'
+import { getModelCatalog as loadModelsDevCache } from '../../../studio/public/model-catalog'
 import { detectHermesHome } from '../runtime/path'
 
 const HERMES_BASE = detectHermesHome()
-const MODELS_DEV_CACHE = resolve(HERMES_BASE, 'models_dev_cache.json')
 const DEFAULT_CONTEXT_LENGTH = 256_000
 
 function fallbackContextLength(options: ModelContextLengthOptions): number {
@@ -86,32 +86,6 @@ function loadConfig(profileDir: string): any | null {
   }
 }
 
-// --- In-memory cache: parsed models_dev_cache (1.7MB), invalidated by mtime ---
-
-let _cache: Record<string, ProviderEntry> | null = null
-let _cacheMtime = 0
-const CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
-let _cacheLoadedAt = 0
-
-function loadModelsDevCache(): Record<string, ProviderEntry> | null {
-  if (!existsSync(MODELS_DEV_CACHE)) return null
-  try {
-    const stat = statSync(MODELS_DEV_CACHE)
-    const now = Date.now()
-    // Return cached if file hasn't changed and within TTL
-    if (_cache && stat.mtimeMs === _cacheMtime && now - _cacheLoadedAt < CACHE_TTL_MS) {
-      return _cache
-    }
-    const raw = readFileSync(MODELS_DEV_CACHE, 'utf-8')
-    _cache = JSON.parse(raw) as Record<string, ProviderEntry>
-    _cacheMtime = stat.mtimeMs
-    _cacheLoadedAt = now
-    return _cache
-  } catch {
-    return _cache // return stale cache on error
-  }
-}
-
 // --- Profile helpers ---
 
 function getProfileDir(profile?: string): string {
@@ -416,7 +390,7 @@ function lookupContextFromCache(config: any, modelName: string, provider: string
  *   3. provider-level providers.<provider>.context_length when the model belongs to that provider
  *   4. custom_providers models.<model>.context_length
  *   5. top-level model.context_length fallback
- *   6. models_dev_cache.json, scoped to model.provider when configured
+ *   6. Studio's shared models.dev catalog, scoped to model.provider when configured
  *   7. DEFAULT_CONTEXT_LENGTH
  */
 /**
@@ -473,7 +447,7 @@ export function getModelContextLength(input?: string | ModelContextLengthOptions
   const configCtx = getConfigContextLength(config)
   if (configCtx && configCtx > 0) return configCtx
 
-  // 4. models_dev_cache.json
+  // 4. Shared local models.dev catalog
   const cached = lookupContextFromCache(config, model, provider)
   if (cached) return cached
 
diff --git a/packages/server/src/modules/studio/infrastructure/database/schemas.ts b/packages/server/src/modules/studio/infrastructure/database/schemas.ts
index e477f48056..30d8e69b15 100644
--- a/packages/server/src/modules/studio/infrastructure/database/schemas.ts
+++ b/packages/server/src/modules/studio/infrastructure/database/schemas.ts
@@ -29,6 +29,7 @@ export const USAGE_SCHEMA: Record<string, string> = {
   is_estimated: 'INTEGER NOT NULL DEFAULT 0',
   cost_usd: 'REAL',
   cost_source: "TEXT NOT NULL DEFAULT 'unknown'",
+  cost_pricing: 'TEXT',
   created_at: 'INTEGER NOT NULL DEFAULT 0',
 }
 
diff --git a/packages/server/src/modules/studio/public/model-catalog.ts b/packages/server/src/modules/studio/public/model-catalog.ts
new file mode 100644
index 0000000000..5b20be6380
--- /dev/null
+++ b/packages/server/src/modules/studio/public/model-catalog.ts
@@ -0,0 +1,2 @@
+export { getModelCatalog, getModelCatalogSnapshot, refreshModelCatalog } from '../services/models/model-catalog'
+export type { CatalogModel, ModelCatalog, ModelCatalogSnapshot } from '../services/models/model-catalog'
diff --git a/packages/server/src/modules/studio/repositories/usage-store.ts b/packages/server/src/modules/studio/repositories/usage-store.ts
index 6c038c57ee..0469f542fa 100644
--- a/packages/server/src/modules/studio/repositories/usage-store.ts
+++ b/packages/server/src/modules/studio/repositories/usage-store.ts
@@ -1,6 +1,7 @@
 import { isSqliteAvailable, getDb, jsonSet, jsonGet, jsonGetAll, jsonDelete } from '../infrastructure/database'
+import { randomUUID } from 'crypto'
 import { USAGE_TABLE as TABLE } from '../infrastructure/database/schemas'
-import { finiteCost, emptyCostCoverage } from '../services/usage/usage-cost'
+import { finiteCost, emptyCostCoverage, type UsageCost, type UsagePriceSnapshot } from '../services/usage/usage-cost'
 import type {
   LocalUsageStats,
   UsageStatsAgentRow,
@@ -37,6 +38,8 @@ function hasUpdatedAtColumn(): boolean {
   }
 }
 
+export type UsageRowRef = { id: number } | { id: string; sessionId: string }
+
 export function updateUsage(
   sessionId: string,
   data: {
@@ -57,8 +60,9 @@ export function updateUsage(
     isEstimated?: boolean
     costUsd?: number
     costSource?: 'reported' | 'estimated'
+    costPricing?: UsagePriceSnapshot
   },
-): void {
+): UsageRowRef | undefined {
   const cacheReadTokens = data.cacheReadTokens ?? 0
   const cacheWriteTokens = data.cacheWriteTokens ?? 0
   const reasoningTokens = data.reasoningTokens ?? 0
@@ -68,6 +72,7 @@ export function updateUsage(
   const profile = data.profile || 'default'
   const costUsd = finiteCost(data.costUsd) ?? null
   const costSource = costUsd == null ? 'unknown' : data.costSource || 'reported'
+  const costPricing = costUsd == null || !data.costPricing ? null : JSON.stringify(data.costPricing)
   if (isSqliteAvailable()) {
     const db = getDb()!
     const columns = [
@@ -90,6 +95,7 @@ export function updateUsage(
       'created_at',
       'cost_usd',
       'cost_source',
+      'cost_pricing',
     ]
     const values = columns.map(() => '?')
     const params = [
@@ -112,17 +118,21 @@ export function updateUsage(
       now,
       costUsd,
       costSource,
+      costPricing,
     ]
     if (hasUpdatedAtColumn()) {
       columns.push('updated_at')
       values.push('?')
       params.push(now)
     }
-    db.prepare(
+    const result = db.prepare(
       `INSERT OR IGNORE INTO ${TABLE} (${columns.join(', ')}) VALUES (${values.join(', ')})`,
     ).run(...params)
+    return result?.changes ? { id: Number(result.lastInsertRowid) } : undefined
   } else {
+    const id = randomUUID()
     jsonSet(TABLE, sessionId, {
+      id,
       run_id: data.runId || '',
       source: data.source || '',
       agent: data.agent || '',
@@ -141,7 +151,25 @@ export function updateUsage(
       created_at: now,
       cost_usd: costUsd,
       cost_source: costSource,
+      cost_pricing: costPricing,
     })
+    return { id, sessionId }
+  }
+}
+
+/** Enrich only the inserted record, without changing its tokens, timestamp, or an existing price. */
+export function fillMissingUsageCost(row: UsageRowRef, cost: UsageCost): void {
+  const amount = finiteCost(cost.costUsd)
+  if (amount === undefined) return
+  const pricing = cost.costPricing ? JSON.stringify(cost.costPricing) : null
+  if (!('sessionId' in row)) {
+    getDb()?.prepare(`UPDATE ${TABLE} SET cost_usd = ?, cost_source = ?, cost_pricing = ? WHERE id = ? AND cost_usd IS NULL`)
+      .run(amount, cost.costSource, pricing, row.id)
+  } else {
+    const saved = jsonGet(TABLE, row.sessionId)
+    if (saved?.id === row.id && saved.cost_usd == null) {
+      jsonSet(TABLE, row.sessionId, { ...saved, cost_usd: amount, cost_source: cost.costSource, cost_pricing: pricing })
+    }
   }
 }
 
diff --git a/packages/server/src/modules/studio/services/models/model-catalog.ts b/packages/server/src/modules/studio/services/models/model-catalog.ts
new file mode 100644
index 0000000000..e963d43497
--- /dev/null
+++ b/packages/server/src/modules/studio/services/models/model-catalog.ts
@@ -0,0 +1,125 @@
+import { createHash, randomUUID } from 'crypto'
+import { readFileSync, statSync } from 'fs'
+import { mkdir, rename, rm, writeFile } from 'fs/promises'
+import { dirname, join } from 'path'
+import { config } from '../../public/config'
+import { logger } from '../../public/logging'
+
+export const MODEL_CATALOG_URL = 'https://models.dev/api.json'
+export const MODEL_CATALOG_PATH = join(config.appHome, 'models', 'models.dev.json')
+const MAX_BYTES = 20 * 1024 * 1024
+const RETRY_MS = 5 * 60_000
+
+export interface CatalogModel {
+  id?: string
+  name?: string
+  limit?: { context?: number; input?: number; output?: number }
+  cost?: Record<string, unknown>
+  reasoning?: boolean
+  attachment?: boolean
+  modalities?: { input?: string[]; output?: string[] }
+}
+export type ModelCatalog = Record<string, { models?: Record<string, CatalogModel> }>
+export interface ModelCatalogSnapshot {
+  data: ModelCatalog
+  fetchedAt: number
+  version: string
+}
+
+function record(value: unknown): value is Record<string, any> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function parseCatalog(raw: string, fetchedAt: number): ModelCatalogSnapshot {
+  if (Buffer.byteLength(raw) > MAX_BYTES) throw new Error('Model catalog is too large')
+  const data: unknown = JSON.parse(raw)
+  if (!record(data) || !Object.keys(data).length) throw new Error('Invalid model catalog')
+  let modelCount = 0
+  for (const provider of Object.values(data)) {
+    if (!record(provider) || !record(provider.models)) throw new Error('Invalid catalog provider')
+    for (const model of Object.values(provider.models)) {
+      if (!record(model) || (model.limit !== undefined && !record(model.limit)) || (model.cost !== undefined && !record(model.cost))) {
+        throw new Error('Invalid catalog model')
+      }
+      modelCount++
+    }
+  }
+  if (!modelCount) throw new Error('Empty model catalog')
+  return { data: data as ModelCatalog, fetchedAt, version: createHash('sha256').update(raw).digest('hex') }
+}
+
+/** One shared disk snapshot; a failed download never replaces the last good copy. */
+export class ModelCatalogCache {
+  private loaded = false
+  private snapshot?: ModelCatalogSnapshot
+  private pending?: Promise<ModelCatalogSnapshot | undefined>
+  private attemptedAt = -Infinity
+
+  constructor(
+    private readonly path: string,
+    private readonly fetcher: typeof fetch = (...args) => fetch(...args),
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  get(): ModelCatalogSnapshot | undefined {
+    if (!this.loaded) {
+      this.loaded = true
+      try {
+        const stat = statSync(this.path)
+        if (stat.size <= MAX_BYTES) this.snapshot = parseCatalog(readFileSync(this.path, 'utf8'), stat.mtimeMs)
+      } catch { /* A first launch may have no cache yet. */ }
+    }
+    return this.snapshot
+  }
+
+  refresh(force = false): Promise<ModelCatalogSnapshot | undefined> {
+    if (this.pending) return this.pending
+    this.get()
+    if (!force && this.now() - this.attemptedAt < RETRY_MS) return Promise.resolve(this.snapshot)
+    this.attemptedAt = this.now()
+    this.pending = this.download().catch(err => {
+      logger.warn({ err }, '[model-catalog] refresh failed; keeping local cache')
+      return this.snapshot
+    }).finally(() => { this.pending = undefined })
+    return this.pending
+  }
+
+  private async download(): Promise<ModelCatalogSnapshot> {
+    const response = await this.fetcher(MODEL_CATALOG_URL, {
+      headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(15_000),
+    })
+    if (!response.ok) throw new Error(`Model catalog HTTP ${response.status}`)
+    if (!response.body) throw new Error('Empty model catalog response')
+    const reader = response.body.getReader()
+    const chunks: Uint8Array[] = []
+    let size = 0
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.byteLength
+        if (size > MAX_BYTES) throw new Error('Model catalog is too large')
+        chunks.push(value)
+      }
+    } finally {
+      await reader.cancel().catch(() => {})
+      reader.releaseLock()
+    }
+    const raw = Buffer.concat(chunks).toString('utf8')
+    const snapshot = parseCatalog(raw, this.now())
+    const temporary = `${this.path}.${randomUUID()}.tmp`
+    await mkdir(dirname(this.path), { recursive: true })
+    try {
+      await writeFile(temporary, raw)
+      await rename(temporary, this.path)
+    } finally { await rm(temporary, { force: true }).catch(() => {}) }
+    this.snapshot = snapshot
+    logger.info({ providers: Object.keys(snapshot.data).length }, '[model-catalog] local catalog updated')
+    return snapshot
+  }
+}
+
+const cache = new ModelCatalogCache(MODEL_CATALOG_PATH)
+export const getModelCatalogSnapshot = () => cache.get()
+export const getModelCatalog = () => cache.get()?.data || null
+export const refreshModelCatalog = (force = false) => cache.refresh(force)
diff --git a/packages/server/src/modules/studio/services/usage/catalog-pricing.ts b/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
new file mode 100644
index 0000000000..4de1c2c7d5
--- /dev/null
+++ b/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
@@ -0,0 +1,71 @@
+import type { ModelCatalogSnapshot } from '../../public/model-catalog'
+import { estimateUsageCost, type UsageCost, type UsagePricing } from './usage-cost'
+
+const providerAliases: Record<string, string> = {
+  gemini: 'google', moonshot: 'moonshotai', kilocode: 'kilo', 'ai-gateway': 'vercel',
+  'opencode-zen': 'opencode', 'opencode-go': 'opencode', 'glm-coding-plan': 'zai-coding-plan',
+  'kimi-coding': 'kimi-for-coding', 'kimi-coding-cn': 'kimi-for-coding', 'xai-oauth': 'xai',
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined
+}
+
+export function estimateCatalogUsageCost(
+  snapshot: ModelCatalogSnapshot | undefined,
+  provider: string,
+  model: string,
+  usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; reasoningTokens?: number },
+  scope: 'run' | 'model_call' = 'run',
+  apiCalls?: number,
+): UsageCost | undefined {
+  if (!snapshot) return
+  const normalized = provider.trim().toLowerCase()
+  const providerId = Object.hasOwn(snapshot.data, normalized) ? normalized : providerAliases[normalized]
+  if (!providerId || !Object.hasOwn(snapshot.data, providerId)) return
+  const models = snapshot.data[providerId].models
+  // Prices are provider-specific. Never borrow a relay's price by a model-name suffix.
+  const entry = models && Object.hasOwn(models, model) ? models[model] : undefined
+  const cost = object(entry?.cost)
+  if (!cost) return
+  let selected = { ...cost }
+  let contextThreshold: number | undefined
+  const prompt = usage.inputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+  let tiers: Array<{ threshold: number; rates: Record<string, unknown> }> = []
+  if (cost.tiers !== undefined) {
+    if (!Array.isArray(cost.tiers)) return
+    for (const value of cost.tiers) {
+      const rates = object(value)
+      const tier = object(rates?.tier)
+      if (!rates || tier?.type !== 'context' || typeof tier.size !== 'number' || !Number.isFinite(tier.size) || tier.size <= 0) return
+      tiers.push({ threshold: tier.size, rates })
+    }
+  }
+  if (!tiers.length && cost.context_over_200k !== undefined) {
+    const rates = object(cost.context_over_200k)
+    if (!rates) return
+    tiers = [{ threshold: 200_000, rates }]
+  }
+  for (const tier of tiers.sort((a, b) => a.threshold - b.threshold)) {
+    if (prompt <= tier.threshold) continue
+    // A whole-run token sum cannot reveal which individual requests crossed a pricing tier.
+    if (scope !== 'model_call' && apiCalls !== 1) return
+    selected = { ...selected, ...tier.rates }
+    contextThreshold = tier.threshold
+  }
+  const rates: UsagePricing = { provider: providerId, model, input: 0, output: 0 }
+  for (const [field, key] of [
+    ['input', 'input'], ['output', 'output'], ['cacheRead', 'cache_read'],
+    ['cacheWrite', 'cache_write'], ['reasoning', 'reasoning'],
+  ] as const) {
+    const value = selected[key]
+    if (value === undefined && key !== 'input' && key !== 'output') continue
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return
+    rates[field] = value
+  }
+  const estimate = estimateUsageCost(usage, rates)
+  return estimate && { ...estimate, costPricing: {
+    source: 'models.dev', rates, catalogVersion: snapshot.version, catalogFetchedAt: snapshot.fetchedAt,
+    ...(contextThreshold === undefined ? {} : { contextThreshold }),
+  } }
+}
diff --git a/packages/server/src/modules/studio/services/usage/usage-cost.ts b/packages/server/src/modules/studio/services/usage/usage-cost.ts
index 16a4c173c3..51b12f6299 100644
--- a/packages/server/src/modules/studio/services/usage/usage-cost.ts
+++ b/packages/server/src/modules/studio/services/usage/usage-cost.ts
@@ -3,6 +3,15 @@ import type { UsageCostCoverage } from '../../contracts/runs/usage'
 export interface UsageCost {
   costUsd: number
   costSource: 'reported' | 'estimated'
+  costPricing?: UsagePriceSnapshot
+}
+
+export interface UsagePriceSnapshot {
+  source: 'manual' | 'models.dev'
+  rates: UsagePricing
+  catalogVersion?: string
+  catalogFetchedAt?: number
+  contextThreshold?: number
 }
 
 export interface UsagePricing {
@@ -12,6 +21,7 @@ export interface UsagePricing {
   output: number
   cacheRead?: number
   cacheWrite?: number
+  reasoning?: number
 }
 
 export function finiteCost(value: unknown): number | undefined {
@@ -43,18 +53,21 @@ export function normalizeUsageCost(value: unknown, source: UsageCost['costSource
   }
 }
 
-export function estimateUsageCost(usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number }, pricing?: UsagePricing): UsageCost | undefined {
+export function estimateUsageCost(usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; reasoningTokens?: number }, pricing?: UsagePricing): UsageCost | undefined {
   if (!pricing) return
+  const separateReasoning = pricing.reasoning === undefined ? 0 : usage.reasoningTokens || 0
+  if (separateReasoning > usage.outputTokens) return
   let costUsd = 0
   for (const [tokens, rate] of [
-    [usage.inputTokens, pricing.input], [usage.outputTokens, pricing.output],
+    [usage.inputTokens, pricing.input], [usage.outputTokens - separateReasoning, pricing.output],
     [usage.cacheReadTokens, pricing.cacheRead], [usage.cacheWriteTokens, pricing.cacheWrite],
+    [separateReasoning, pricing.reasoning],
   ]) {
     if (!tokens) continue
     if (rate === undefined || finiteCost(rate) === undefined) return
     costUsd += tokens * rate / 1_000_000
   }
-  // Reasoning tokens are already included in output; never charge them twice.
+  // Reasoning is included in output; a separate rate replaces, rather than adds to, its output charge.
   return Number.isFinite(costUsd) ? { costUsd, costSource: 'estimated' } : undefined
 }
 
diff --git a/packages/server/src/modules/studio/services/usage/usage-recorder.ts b/packages/server/src/modules/studio/services/usage/usage-recorder.ts
index 551fdaf57b..a9aa1c2787 100644
--- a/packages/server/src/modules/studio/services/usage/usage-recorder.ts
+++ b/packages/server/src/modules/studio/services/usage/usage-recorder.ts
@@ -1,7 +1,9 @@
 import { logger } from '../../public/logging'
-import { updateUsage } from '../../repositories/usage-store'
+import { updateUsage, fillMissingUsageCost } from '../../repositories/usage-store'
 import { getUsagePricing } from '../../repositories/usage-pricing-store'
+import { getModelCatalogSnapshot, refreshModelCatalog } from '../../public/model-catalog'
 import { normalizeUsageCost, estimateUsageCost, type UsageCost } from './usage-cost'
+import { estimateCatalogUsageCost } from './catalog-pricing'
 
 export interface NormalizedTokenUsage {
   inputTokens: number
@@ -114,16 +116,23 @@ export function recordSessionUsage(input: RecordSessionUsageInput): NormalizedTo
   const usage = normalizeTokenUsage(input.usage, input.fallbackUsage)
   try {
     let cost = normalizeUsageCost(input.cost) || normalizeUsageCost(input.usage)
+    let hasManualPricing = false
     if (!cost && input.model && input.provider) {
       try {
         const pricing = getUsagePricing(input.profile || 'default')
           .find(row => row.provider === input.provider && row.model === input.model)
+        hasManualPricing = !!pricing
         cost = estimateUsageCost(usage, pricing)
+        if (cost && pricing) cost.costPricing = { source: 'manual', rates: pricing }
       } catch (err) {
         logger.warn({ err }, '[usage-recorder] failed to read model pricing')
       }
     }
-    updateUsage(input.sessionId, {
+    const catalog = !cost && !hasManualPricing ? getModelCatalogSnapshot() : undefined
+    if (!cost && !hasManualPricing && input.provider && input.model) {
+      cost = estimateCatalogUsageCost(catalog, input.provider, input.model, usage, input.usageScope, input.apiCalls)
+    }
+    const row = updateUsage(input.sessionId, {
       runId: input.runId || '',
       source: input.source,
       agent: input.agent,
@@ -141,6 +150,16 @@ export function recordSessionUsage(input: RecordSessionUsageInput): NormalizedTo
       isEstimated: input.isEstimated ?? usage.isEstimated,
       ...(cost || {}),
     })
+    // Cold start: persist tokens immediately, then fill this new row after the shared download.
+    // Replays return no inserted row, so a later catalog never reprices historical usage.
+    if (row && !cost && !hasManualPricing && !catalog && input.provider && input.model) {
+      const provider = input.provider
+      const model = input.model
+      void refreshModelCatalog().then(snapshot => {
+        const estimate = estimateCatalogUsageCost(snapshot, provider, model, usage, input.usageScope, input.apiCalls)
+        if (estimate) fillMissingUsageCost(row, estimate)
+      }).catch(err => logger.warn({ err }, '[usage-recorder] failed to fill catalog cost'))
+    }
   } catch (err) {
     logger.warn({
       err,
diff --git a/tests/server/model-catalog.test.ts b/tests/server/model-catalog.test.ts
new file mode 100644
index 0000000000..00d7a18589
--- /dev/null
+++ b/tests/server/model-catalog.test.ts
@@ -0,0 +1,127 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join } from 'path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ModelCatalogCache, MODEL_CATALOG_URL } from '../../packages/server/src/modules/studio/services/models/model-catalog'
+import { estimateCatalogUsageCost } from '../../packages/server/src/modules/studio/services/usage/catalog-pricing'
+
+const catalog = (input = 2) => ({ openai: { models: {
+  model: { limit: { context: 300_000, output: 32_000 }, cost: {
+    input, output: 8, cache_read: 0.2, cache_write: 2.5,
+    tiers: [{ input: 4, output: 12, cache_read: 0.4, tier: { type: 'context', size: 200_000 } }],
+  } },
+} } })
+const snapshot = (data: any = catalog()) => ({ data, version: 'test-version', fetchedAt: 1234 })
+
+describe('shared models.dev cache', () => {
+  let directory: string
+  let path: string
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'studio-catalog-'))
+    path = join(directory, 'models', 'models.dev.json')
+  })
+  afterEach(() => rmSync(directory, { recursive: true, force: true }))
+
+  it('downloads once for concurrent callers and reloads the same raw JSON offline after restart', async () => {
+    const fetcher = vi.fn(async () => new Response(JSON.stringify(catalog())))
+    const cache = new ModelCatalogCache(path, fetcher)
+    expect(cache.get()).toBeUndefined()
+    const [one, two] = await Promise.all([cache.refresh(true), cache.refresh()])
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    expect(fetcher).toHaveBeenCalledWith(MODEL_CATALOG_URL, expect.objectContaining({ headers: { Accept: 'application/json' } }))
+    expect(one).toBe(two)
+    expect(JSON.parse(readFileSync(path, 'utf8'))).toEqual(catalog())
+    expect(new ModelCatalogCache(path, fetcher).get()?.data.openai.models?.model.limit?.context).toBe(300_000)
+    await cache.refresh()
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    await cache.refresh(true)
+    expect(fetcher).toHaveBeenCalledTimes(2)
+  })
+
+  it('refreshes an existing snapshot and gives new costs a new version without mutating old snapshots', async () => {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(catalog()))
+    const cache = new ModelCatalogCache(path, vi.fn(async () => new Response(JSON.stringify(catalog(3)))))
+    const old = cache.get()!
+    const updated = (await cache.refresh(true))!
+    expect(updated.version).not.toBe(old.version)
+    expect(old.data.openai.models?.model.cost?.input).toBe(2)
+    expect(cache.get()?.data.openai.models?.model.cost?.input).toBe(3)
+  })
+
+  it.each(['network', 'http', 'json', 'empty', 'shape', 'truncated', 'oversized'])('keeps a valid local file after a %s failure', async failure => {
+    const raw = JSON.stringify(catalog())
+    mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, raw)
+    const fetcher = vi.fn(async () => {
+      if (failure === 'network') throw new Error('offline')
+      if (failure === 'http') return new Response('Unavailable', { status: 503 })
+      if (failure === 'oversized') return new Response(new Uint8Array(21 * 1024 * 1024))
+      if (failure === 'truncated') return new Response(new ReadableStream({ start(c) { c.error(new Error('connection closed')) } }))
+      return new Response(failure === 'json' ? '<html>error</html>' : failure === 'empty' ? '{}' : '{"openai":{"models":[]}}')
+    })
+    const cache = new ModelCatalogCache(path, fetcher)
+    expect((await cache.refresh(true))?.data).toEqual(catalog())
+    expect(readFileSync(path, 'utf8')).toBe(raw)
+    await cache.refresh()
+    expect(fetcher).toHaveBeenCalledTimes(1)
+  })
+
+  it('recovers from a corrupt cache and leaves cold offline lookups unknown', async () => {
+    mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, '{')
+    const cache = new ModelCatalogCache(path, vi.fn(async () => new Response(JSON.stringify(catalog()))))
+    expect(cache.get()).toBeUndefined()
+    expect((await cache.refresh(true))?.data).toEqual(catalog())
+    const offline = new ModelCatalogCache(join(directory, 'missing.json'), vi.fn(async () => { throw new Error('offline') }))
+    expect(await offline.refresh()).toBeUndefined()
+  })
+})
+
+describe('catalog cost estimates', () => {
+  const usage = { inputTokens: 1000, outputTokens: 200, reasoningTokens: 100, cacheReadTokens: 5000, cacheWriteTokens: 100 }
+
+  it('prices disjoint token categories and retains the rates, source and catalog version', () => {
+    const cost = estimateCatalogUsageCost(snapshot(), 'openai', 'model', usage)!
+    expect(cost.costUsd).toBeCloseTo(0.00485)
+    expect(cost).toMatchObject({ costSource: 'estimated', costPricing: { source: 'models.dev', catalogVersion: 'test-version', catalogFetchedAt: 1234, rates: { provider: 'openai', model: 'model', input: 2 } } })
+  })
+
+  it('uses explicit context tiers, including cache tokens, only when individual request size is known', () => {
+    const large = { ...usage, inputTokens: 195_000, cacheReadTokens: 5000, cacheWriteTokens: 0 }
+    expect(estimateCatalogUsageCost(snapshot(), 'openai', 'model', large, 'model_call')?.costPricing?.contextThreshold).toBeUndefined()
+    large.inputTokens++
+    expect(estimateCatalogUsageCost(snapshot(), 'openai', 'model', large, 'model_call')?.costPricing).toMatchObject({ contextThreshold: 200_000, rates: { input: 4, output: 12 } })
+    expect(estimateCatalogUsageCost(snapshot(), 'openai', 'model', large, 'run')).toBeUndefined()
+    expect(estimateCatalogUsageCost(snapshot(), 'openai', 'model', large, 'run', 1)?.costPricing?.contextThreshold).toBe(200_000)
+  })
+
+  it('handles legacy context pricing without confusing a newer explicit tier with the legacy 200k name', () => {
+    const data: any = catalog()
+    data.openai.models.model.cost.tiers[0].tier.size = 272_000
+    data.openai.models.model.cost.context_over_200k = { input: 6, output: 20 }
+    const request = { ...usage, inputTokens: 210_000 }
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', request, 'model_call')?.costPricing?.rates.input).toBe(2)
+    delete data.openai.models.model.cost.tiers
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', request, 'model_call')?.costPricing?.rates.input).toBe(6)
+  })
+
+  it('never guesses relay prices or treats incomplete/malformed prices as free', () => {
+    expect(estimateCatalogUsageCost(snapshot(), 'custom:relay', 'model', usage)).toBeUndefined()
+    expect(estimateCatalogUsageCost(snapshot(), 'openai', 'Model', usage)).toBeUndefined()
+    for (const bad of [undefined, null, -1, Infinity, '2']) {
+      const data: any = catalog(); data.openai.models.model.cost.input = bad
+      expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', usage)).toBeUndefined()
+    }
+    const data: any = catalog(); delete data.openai.models.model.cost.cache_read
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', usage)).toBeUndefined()
+    data.openai.models.model.cost = { input: 0, output: 0, cache_read: 0, cache_write: 0 }
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', usage)?.costUsd).toBe(0)
+  })
+
+  it('supports known provider aliases and separate reasoning rates without double charging', () => {
+    const data: any = { google: catalog().openai }
+    data.google.models.model.cost.reasoning = 4
+    expect(estimateCatalogUsageCost(snapshot(data), 'gemini', 'model', usage)?.costUsd).toBeCloseTo(0.00445)
+    data.google.models.model.cost.tiers = [{ tier: { type: 'unknown', size: 1 }, input: 5 }]
+    expect(estimateCatalogUsageCost(snapshot(data), 'gemini', 'model', usage)).toBeUndefined()
+  })
+})
diff --git a/tests/server/model-context.test.ts b/tests/server/model-context.test.ts
index 4233b7d38a..d09e74d746 100644
--- a/tests/server/model-context.test.ts
+++ b/tests/server/model-context.test.ts
@@ -7,6 +7,7 @@ let homeDir = ''
 const originalHermesHome = process.env.HERMES_HOME
 const originalLocalAppData = process.env.LOCALAPPDATA
 const originalAppData = process.env.APPDATA
+const originalStudioHome = process.env.HERMES_WEB_UI_HOME
 
 function hermesPath(...parts: string[]) {
   return join(homeDir, '.hermes', ...parts)
@@ -18,8 +19,9 @@ function writeConfig(content: string) {
 }
 
 function writeModelsCache(data: Record<string, unknown>) {
-  mkdirSync(hermesPath(), { recursive: true })
-  writeFileSync(hermesPath('models_dev_cache.json'), JSON.stringify(data))
+  const directory = join(homeDir, 'studio', 'models')
+  mkdirSync(directory, { recursive: true })
+  writeFileSync(join(directory, 'models.dev.json'), JSON.stringify(data))
 }
 
 async function loadModelContext() {
@@ -45,9 +47,11 @@ async function loadModelContext() {
 describe('getModelContextLength', () => {
   beforeEach(() => {
     homeDir = mkdtempSync(join(tmpdir(), 'hwui-model-context-'))
+    process.env.HERMES_WEB_UI_HOME = join(homeDir, 'studio')
   })
 
   afterEach(() => {
+    vi.unstubAllGlobals()
     vi.doUnmock('os')
     vi.doUnmock('../../packages/server/src/modules/studio/public/provider-context')
     if (originalHermesHome === undefined) delete process.env.HERMES_HOME
@@ -56,10 +60,27 @@ describe('getModelContextLength', () => {
     else process.env.LOCALAPPDATA = originalLocalAppData
     if (originalAppData === undefined) delete process.env.APPDATA
     else process.env.APPDATA = originalAppData
+    if (originalStudioHome === undefined) delete process.env.HERMES_WEB_UI_HOME
+    else process.env.HERMES_WEB_UI_HOME = originalStudioHome
     if (homeDir) rmSync(homeDir, { recursive: true, force: true })
     homeDir = ''
   })
 
+  it('uses the shared catalog for context/output limits and observes a startup refresh without restarting', async () => {
+    writeModelsCache({ openai: { models: { 'catalog-model': { limit: { context: 100_000, output: 10_000 } } } } })
+    const { getModelRuntimeCapabilities } = await loadModelContext()
+    const { refreshModelCatalog } = await import('../../packages/server/src/modules/studio/public/model-catalog')
+    const input = { provider: 'openai', model: 'catalog-model' }
+    expect(getModelRuntimeCapabilities(input)).toMatchObject({ contextWindow: 100_000, outputLimit: 10_000 })
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ openai: { models: {
+      'catalog-model': { limit: { context: 300_000, output: 32_000 }, reasoning: true, modalities: { input: ['text', 'image'] } },
+    } } }))))
+    await refreshModelCatalog(true)
+    expect(getModelRuntimeCapabilities(input)).toEqual({ contextWindow: 300_000, outputLimit: 32_000, reasoning: true, input: ['text', 'image'] })
+    writeConfig('model:\n  context_length: 80000\n')
+    expect(getModelRuntimeCapabilities(input).contextWindow).toBe(80_000)
+  })
+
   it.each([false, true])('prefers the manually edited model window (config file exists: %s)', async withConfig => {
     if (withConfig) writeConfig('model:\n  default: policy-model\n  provider: test\n  context_length: 256000\n')
     const readModelContextRecord = vi.fn(() => ({ available: true, row: { context_limit: 80000 } }))
diff --git a/tests/server/usage-cost.test.ts b/tests/server/usage-cost.test.ts
index 9c66391431..0b5c777c98 100644
--- a/tests/server/usage-cost.test.ts
+++ b/tests/server/usage-cost.test.ts
@@ -5,10 +5,12 @@ import { applyHermesCostFallbacks } from '../../packages/server/src/modules/stud
 import { NativeTurnUsage } from '../../packages/server/src/modules/coding-agents/services/runtime/native-usage'
 import { USAGE_SCHEMA, USAGE_RUN_INDEX, USAGE_PRICING_SCHEMA } from '../../packages/server/src/modules/studio/infrastructure/database/schemas'
 import { recordSessionUsage } from '../../packages/server/src/modules/studio/services/usage/usage-recorder'
-import { getLocalUsageStats, getUnpricedHermesUsageSessions } from '../../packages/server/src/modules/studio/repositories/usage-store'
+import { getLocalUsageStats, getUnpricedHermesUsageSessions, updateUsage, fillMissingUsageCost } from '../../packages/server/src/modules/studio/repositories/usage-store'
 import { getUsagePricing, saveUsagePricing, validateUsagePricing } from '../../packages/server/src/modules/studio/services/usage/usage-pricing'
 
 let db: DatabaseSync
+const catalogMock = vi.hoisted(() => ({ getModelCatalogSnapshot: vi.fn(), refreshModelCatalog: vi.fn() }))
+vi.mock('../../packages/server/src/modules/studio/public/model-catalog', () => catalogMock)
 vi.mock('../../packages/server/src/modules/studio/infrastructure/database/index', () => ({
   isSqliteAvailable: () => true, getDb: () => db,
   jsonGet: vi.fn(), jsonSet: vi.fn(), jsonGetAll: vi.fn(), jsonDelete: vi.fn(),
@@ -16,6 +18,8 @@ vi.mock('../../packages/server/src/modules/studio/infrastructure/database/index'
 
 describe('usage cost accounting', () => {
   beforeEach(() => {
+    catalogMock.getModelCatalogSnapshot.mockReset()
+    catalogMock.refreshModelCatalog.mockReset().mockResolvedValue(undefined)
     db = new DatabaseSync(':memory:')
     db.exec(`CREATE TABLE session_usage (${Object.entries(USAGE_SCHEMA).map(([key, sql]) => `${key} ${sql}`).join(',')}); ${USAGE_RUN_INDEX};
       CREATE TABLE usage_pricing (${Object.entries(USAGE_PRICING_SCHEMA).map(([key, sql]) => `${key} ${sql}`).join(',')});`)
@@ -113,4 +117,60 @@ describe('usage cost accounting', () => {
     expect(tracker.rows('grok', undefined)).toMatchObject([{ usage: { inputTokens: 30 }, cost: { costUsd: 0.07, costSource: 'estimated' } }])
   })
 
+  const catalogSnapshot = { version: 'catalog-v1', fetchedAt: 1234, data: { global: { models: {
+    'test-model': { cost: { input: 2, output: 8, cache_read: 0.2 } },
+  } } } }
+
+  it('persists catalog estimates and the exact pricing snapshot, with reported and manual costs taking priority', () => {
+    catalogMock.getModelCatalogSnapshot.mockReturnValue(catalogSnapshot)
+    record('catalog', { inputTokens: 1000, outputTokens: 200, cacheReadTokens: 5000 })
+    const saved = db.prepare('SELECT * FROM session_usage').get() as any
+    expect(saved.cost_usd).toBeCloseTo(0.0046)
+    expect(JSON.parse(saved.cost_pricing)).toMatchObject({ source: 'models.dev', catalogVersion: 'catalog-v1', rates: { input: 2 } })
+    saveUsagePricing('p', [{ provider: 'global', model: 'test-model', input: 4, output: 16, cacheRead: 0.4 }])
+    record('manual', { inputTokens: 1000, outputTokens: 200, cacheReadTokens: 5000 })
+    record('reported', { inputTokens: 1000, outputTokens: 200, cost: 0 })
+    const rows = db.prepare('SELECT * FROM session_usage ORDER BY id').all() as any[]
+    expect(rows.map(row => row.cost_usd)).toEqual([0.0046, 0.0092, 0])
+    expect(JSON.parse(rows[1].cost_pricing).source).toBe('manual')
+    expect(rows[2].cost_pricing).toBeNull()
+    expect(catalogMock.refreshModelCatalog).not.toHaveBeenCalled()
+  })
+
+  it('fills a cold-start record after download without duplicating tokens or repricing a replay', async () => {
+    let finish!: (snapshot: unknown) => void
+    catalogMock.refreshModelCatalog.mockReturnValue(new Promise(resolve => { finish = resolve }))
+    record('cold', { inputTokens: 1000, outputTokens: 200 })
+    record('cold', { inputTokens: 1000, outputTokens: 200 })
+    const before = db.prepare('SELECT * FROM session_usage').get() as any
+    expect(before.cost_usd).toBeNull()
+    expect(catalogMock.refreshModelCatalog).toHaveBeenCalledTimes(1)
+    finish(catalogSnapshot)
+    await vi.waitFor(() => expect(getLocalUsageStats('p', 1).cost).toBeCloseTo(0.0036))
+    const after = db.prepare('SELECT * FROM session_usage').get() as any
+    expect(after.created_at).toBe(before.created_at)
+    expect(getLocalUsageStats('p', 1).input_tokens).toBe(1000)
+    catalogMock.getModelCatalogSnapshot.mockReturnValue({ ...catalogSnapshot, version: 'new' })
+    record('cold', { inputTokens: 9000, outputTokens: 9000 })
+    expect(db.prepare('SELECT * FROM session_usage').get()).toEqual(after)
+  })
+
+  it('does not replace an explicit partial manual price with catalog rates', () => {
+    catalogMock.getModelCatalogSnapshot.mockReturnValue(catalogSnapshot)
+    saveUsagePricing('p', [{ provider: 'global', model: 'test-model', input: 1, output: 2 }])
+    record('missing-cache', { inputTokens: 1000, outputTokens: 200, cacheReadTokens: 5000 })
+    expect(getLocalUsageStats('p', 1).cost_coverage?.unknown).toBe(1)
+    expect(catalogMock.refreshModelCatalog).not.toHaveBeenCalled()
+  })
+
+  it('late enrichment cannot overwrite a known cost or restore a deleted row', () => {
+    const ref = updateUsage('one', { inputTokens: 10, outputTokens: 1 })!
+    fillMissingUsageCost(ref, { costUsd: 0, costSource: 'reported' })
+    fillMissingUsageCost(ref, { costUsd: 5, costSource: 'estimated' })
+    expect((db.prepare('SELECT cost_usd FROM session_usage').get() as any).cost_usd).toBe(0)
+    db.exec('DELETE FROM session_usage')
+    fillMissingUsageCost(ref, { costUsd: 5, costSource: 'estimated' })
+    expect(db.prepare('SELECT * FROM session_usage').all()).toEqual([])
+  })
+
 })
diff --git a/tests/server/usage-store.test.ts b/tests/server/usage-store.test.ts
index f69bd9c00a..b743226500 100644
--- a/tests/server/usage-store.test.ts
+++ b/tests/server/usage-store.test.ts
@@ -21,6 +21,7 @@ vi.mock('../../packages/server/src/modules/studio/infrastructure/database/index'
 
 import {
   updateUsage,
+  fillMissingUsageCost,
   getUsage,
   getUsageBatch,
   deleteUsage,
@@ -66,6 +67,21 @@ describe('Usage Store (JSON fallback)', () => {
     expect(mockJsonGet).toHaveBeenCalledWith('session_usage', 'session-1')
   })
 
+  it('fills JSON costs only for the same unpriced row, preserving newer usage and known zero costs', () => {
+    const ref = updateUsage('session-1', { inputTokens: 100, outputTokens: 50 })!
+    const saved = mockJsonSet.mock.calls[0][2]
+    mockJsonGet.mockReturnValue(saved)
+    const cost = { costUsd: 0.25, costSource: 'estimated' as const }
+    fillMissingUsageCost(ref, cost)
+    expect(mockJsonSet).toHaveBeenLastCalledWith('session_usage', 'session-1', { ...saved, cost_usd: 0.25, cost_source: 'estimated', cost_pricing: null })
+    mockJsonSet.mockClear()
+    for (const newer of [undefined, { ...saved, id: 'another-row' }, { ...saved, cost_usd: 0 }]) {
+      mockJsonGet.mockReturnValue(newer)
+      fillMissingUsageCost(ref, cost)
+    }
+    expect(mockJsonSet).not.toHaveBeenCalled()
+  })
+
   it('getUsage returns undefined when jsonGet returns nothing', () => {
     mockJsonGet.mockReturnValue(undefined)
     const result = getUsage('nonexistent')
@@ -189,6 +205,7 @@ describe('Usage Store (SQLite path)', () => {
       expect.any(Number), // created_at
       null, // costUsd
       'unknown', // costSource
+      null, // costPricing
     )
   })
 
@@ -221,6 +238,7 @@ describe('Usage Store (SQLite path)', () => {
       expect.any(Number), // created_at
       null, // costUsd
       'unknown', // costSource
+      null, // costPricing
       expect.any(Number), // updated_at
     )
   })

From 824a91255d9a210a9a8edb235c2fae0d2f3e2911 Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Tue, 29 Sep 2026 22:09:40 +0800
Subject: [PATCH 3/8] match GLM Coding Plan to the model catalog

---
 docs/harness/usage-cost.md                           |  5 +++++
 .../src/modules/hermes/services/models/context.ts    |  1 +
 .../modules/studio/services/usage/catalog-pricing.ts |  1 +
 tests/server/model-catalog.test.ts                   | 12 ++++++++++++
 tests/server/model-context.test.ts                   | 12 ++++++++++++
 5 files changed, 31 insertions(+)

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index 22acc56fe6..2054a7eb1a 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -45,6 +45,11 @@ tokens; a run aggregate above a tier threshold stays unknown unless it represent
 a single API call. Explicit tiers take precedence over legacy `context_over_200k`.
 Separate reasoning rates replace the reasoning portion of the output charge.
 
+Studio's built-in `glm` points to the domestic GLM Coding Plan endpoint and maps
+to `zhipuai-coding-plan` for both pricing and context limits. It does not borrow
+`zai`/`zhipuai` metered API prices. A catalog plan rate of zero is retained as an
+estimate; it does not account for the subscription fee or imply a free plan.
+
 Estimated records retain nullable `cost_pricing` JSON with the rate source,
 effective USD-per-million rates, catalog SHA-256 version, download time and
 selected context threshold. `cost_source` remains `estimated`, so existing
diff --git a/packages/server/src/modules/hermes/services/models/context.ts b/packages/server/src/modules/hermes/services/models/context.ts
index 505d933bc2..4821b268b8 100644
--- a/packages/server/src/modules/hermes/services/models/context.ts
+++ b/packages/server/src/modules/hermes/services/models/context.ts
@@ -68,6 +68,7 @@ const MODEL_CACHE_PROVIDER_ALIASES: Record<string, string[]> = {
   'ai-gateway': ['vercel'],
   'opencode-zen': ['opencode'],
   'opencode-go': ['opencode'],
+  glm: ['zhipuai-coding-plan'],
   'glm-coding-plan': ['zai-coding-plan'],
   'kimi-coding': ['kimi-for-coding'],
   'kimi-coding-cn': ['kimi-for-coding'],
diff --git a/packages/server/src/modules/studio/services/usage/catalog-pricing.ts b/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
index 4de1c2c7d5..2a9b0bcfa0 100644
--- a/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
+++ b/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
@@ -3,6 +3,7 @@ import { estimateUsageCost, type UsageCost, type UsagePricing } from './usage-co
 
 const providerAliases: Record<string, string> = {
   gemini: 'google', moonshot: 'moonshotai', kilocode: 'kilo', 'ai-gateway': 'vercel',
+  glm: 'zhipuai-coding-plan',
   'opencode-zen': 'opencode', 'opencode-go': 'opencode', 'glm-coding-plan': 'zai-coding-plan',
   'kimi-coding': 'kimi-for-coding', 'kimi-coding-cn': 'kimi-for-coding', 'xai-oauth': 'xai',
 }
diff --git a/tests/server/model-catalog.test.ts b/tests/server/model-catalog.test.ts
index 00d7a18589..3683007b82 100644
--- a/tests/server/model-catalog.test.ts
+++ b/tests/server/model-catalog.test.ts
@@ -124,4 +124,16 @@ describe('catalog cost estimates', () => {
     data.google.models.model.cost.tiers = [{ tier: { type: 'unknown', size: 1 }, input: 5 }]
     expect(estimateCatalogUsageCost(snapshot(data), 'gemini', 'model', usage)).toBeUndefined()
   })
+
+  it('matches glm to domestic Coding Plan rates without borrowing metered API prices', () => {
+    const data = {
+      'zhipuai-coding-plan': { models: { 'glm-5.3-flash': { cost: { input: 0, output: 0, cache_read: 0, cache_write: 0 } } } },
+      zai: { models: { 'glm-5.3-flash': { cost: { input: 0.15, output: 0.5, cache_read: 0.03, cache_write: 0 } } } },
+    }
+    expect(estimateCatalogUsageCost(snapshot(data), 'glm', 'glm-5.3-flash', usage)).toMatchObject({
+      costUsd: 0, costSource: 'estimated', costPricing: { rates: { provider: 'zhipuai-coding-plan' } },
+    })
+    expect(estimateCatalogUsageCost(snapshot({ zai: data.zai }), 'glm', 'glm-5.3-flash', usage)).toBeUndefined()
+    expect(estimateCatalogUsageCost(snapshot(data), 'custom:glm', 'glm-5.3-flash', usage)).toBeUndefined()
+  })
 })
diff --git a/tests/server/model-context.test.ts b/tests/server/model-context.test.ts
index d09e74d746..9c091d9bf9 100644
--- a/tests/server/model-context.test.ts
+++ b/tests/server/model-context.test.ts
@@ -105,6 +105,18 @@ describe('getModelContextLength', () => {
     expect(getModelContextLength()).toBe(256_000)
   })
 
+  it('matches Studio glm to the domestic Coding Plan for context and output limits', async () => {
+    writeConfig('model:\n  default: glm-5.3-flash\n  provider: glm\n')
+    writeModelsCache({
+      'zhipuai-coding-plan': { models: { 'glm-5.3-flash': { limit: { context: 1_000_000, output: 131_072 } } } },
+      zai: { models: { 'glm-5.3-flash': { limit: { context: 200_000, output: 32_000 } } } },
+    })
+    const { getModelContextLength, getModelRuntimeCapabilities } = await loadModelContext()
+    expect(getModelContextLength()).toBe(1_000_000)
+    expect(getModelRuntimeCapabilities({ provider: 'glm', model: 'glm-5.3-flash' }))
+      .toMatchObject({ contextWindow: 1_000_000, outputLimit: 131_072 })
+  })
+
   it('uses a caller-provided fallback only when no model context is configured', async () => {
     writeConfig(`model:\n  default: grok-4.6\n  provider: custom:grok\n`)
 

From 650c038f51deebd223e95bc3cd8dc74a3ef41d0b Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Tue, 29 Sep 2026 22:26:11 +0800
Subject: [PATCH 4/8] show sub-cent usage costs with higher precision

---
 docs/harness/usage-cost.md              |  6 ++++++
 packages/client/src/utils/usage-cost.ts |  4 +++-
 tests/client/usage-cost.test.ts         | 13 ++++++++++++-
 tests/e2e/usage-cost.spec.ts            |  8 ++++++++
 4 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index 2054a7eb1a..96c2213b8a 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -10,6 +10,12 @@ Studio keeps `total_cost` and daily `cost` numeric for older clients. New
 "Not recorded" for wholly unknown usage and label partial totals. Empty days
 still show zero. A provider report is not a reconciled account invoice.
 
+Studio and App display USD amounts with two to six decimal places, trimming
+trailing zeros. Positive amounts below one millionth of a dollar show
+`<$0.000001`. This keeps sub-cent calls visible in totals and daily costs instead
+of rendering different amounts with the same `<$0.01` label. Storage retains the
+original precision.
+
 The Usage page's Model pricing dialog stores Profile-scoped USD prices per
 million ordinary input, output, cache read and cache write tokens. Provider and
 model IDs must match exactly; no cross-provider model-name fallback is used.
diff --git a/packages/client/src/utils/usage-cost.ts b/packages/client/src/utils/usage-cost.ts
index 7d910f4592..d6dc4c5eaa 100644
--- a/packages/client/src/utils/usage-cost.ts
+++ b/packages/client/src/utils/usage-cost.ts
@@ -13,5 +13,7 @@ export function usageCostState(amount: number, coverage?: UsageCostCoverage, has
 export function formatUsageCost(amount: number, coverage?: UsageCostCoverage, hasActivity = true): string | null {
   if (usageCostState(amount, coverage, hasActivity) === 'unknown') return null
   if (amount === 0) return '$0.00'
-  return amount < 0.01 ? '<$0.01' : `$${amount.toFixed(2)}`
+  if (amount < 0.000001) return '<$0.000001'
+  // Keep small token charges visible in both daily amounts and larger totals.
+  return `$${amount.toFixed(6).replace(/(\.\d{2,}?)0+$/, '$1')}`
 }
diff --git a/tests/client/usage-cost.test.ts b/tests/client/usage-cost.test.ts
index 9225ea8f7f..984c5693bd 100644
--- a/tests/client/usage-cost.test.ts
+++ b/tests/client/usage-cost.test.ts
@@ -7,7 +7,7 @@ describe('usage cost presentation', () => {
     expect(formatUsageCost(0, { reported: 1, estimated: 0, unknown: 0 })).toBe('$0.00')
     expect(formatUsageCost(0)).toBeNull()
     expect(formatUsageCost(0, undefined, false)).toBe('$0.00')
-    expect(formatUsageCost(0.001)).toBe('<$0.01')
+    expect(formatUsageCost(0.001)).toBe('$0.001')
   })
   it('identifies partial coverage and estimates without losing the known amount', () => {
     const partial = { reported: 2, estimated: 1, unknown: 1 }
@@ -16,4 +16,15 @@ describe('usage cost presentation', () => {
     expect(usageCostState(1, { reported: 0, estimated: 1, unknown: 0 })).toBe('estimated')
     expect(usageCostState(1, { reported: 1, estimated: 1, unknown: 0 })).toBe('mixed')
   })
+
+  it('shows small charges changing the total instead of hiding both below one cent', () => {
+    const coverage = { reported: 0, estimated: 3, unknown: 9 }
+    expect(formatUsageCost(0.002887398, coverage)).toBe('$0.002887')
+    expect(formatUsageCost(0.004529376, coverage)).toBe('$0.004529')
+    expect(formatUsageCost(10.001641978, coverage)).toBe('$10.001642')
+    expect(formatUsageCost(0.000001, coverage)).toBe('$0.000001')
+    expect(formatUsageCost(0.0000001, coverage)).toBe('<$0.000001')
+    expect(formatUsageCost(10, coverage)).toBe('$10.00')
+    expect(formatUsageCost(0.1, coverage)).toBe('$0.10')
+  })
 })
diff --git a/tests/e2e/usage-cost.spec.ts b/tests/e2e/usage-cost.spec.ts
index 33a2c0554f..fea0e40d5b 100644
--- a/tests/e2e/usage-cost.spec.ts
+++ b/tests/e2e/usage-cost.spec.ts
@@ -25,6 +25,14 @@ test('shows unknown, partial and free costs and saves explicit model pricing', a
   await page.getByRole('button', { name: 'Refresh', exact: true }).click()
   await expect(card.getByText('$0.25', { exact: true })).toBeVisible()
   await expect(card.getByText('Partial cost; some usage is unpriced')).toBeVisible()
+  coverage = { reported: 0, estimated: 1, unknown: 1 }; cost = 0.002887398
+  await page.getByRole('button', { name: 'Refresh', exact: true }).click()
+  await expect(card.getByText('$0.002887', { exact: true })).toBeVisible()
+  await expect(page.locator('tbody')).toContainText('$0.002887')
+  coverage = { reported: 0, estimated: 3, unknown: 1 }; cost = 0.004529376
+  await page.getByRole('button', { name: 'Refresh', exact: true }).click()
+  await expect(card.getByText('$0.004529', { exact: true })).toBeVisible()
+  await expect(page.locator('tbody')).toContainText('$0.004529')
   coverage = { reported: 1, estimated: 0, unknown: 0 }; cost = 0
   await page.getByRole('button', { name: 'Refresh', exact: true }).click()
   await expect(card.getByText('$0.00', { exact: true })).toBeVisible()

From 140deb54ebeef83f1a2ff95c4f6c56cfabc07b6d Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Tue, 29 Sep 2026 22:29:48 +0800
Subject: [PATCH 5/8] Revert "show sub-cent usage costs with higher precision"

This reverts commit 650c038f51deebd223e95bc3cd8dc74a3ef41d0b.
---
 docs/harness/usage-cost.md              |  6 ------
 packages/client/src/utils/usage-cost.ts |  4 +---
 tests/client/usage-cost.test.ts         | 13 +------------
 tests/e2e/usage-cost.spec.ts            |  8 --------
 4 files changed, 2 insertions(+), 29 deletions(-)

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index 96c2213b8a..2054a7eb1a 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -10,12 +10,6 @@ Studio keeps `total_cost` and daily `cost` numeric for older clients. New
 "Not recorded" for wholly unknown usage and label partial totals. Empty days
 still show zero. A provider report is not a reconciled account invoice.
 
-Studio and App display USD amounts with two to six decimal places, trimming
-trailing zeros. Positive amounts below one millionth of a dollar show
-`<$0.000001`. This keeps sub-cent calls visible in totals and daily costs instead
-of rendering different amounts with the same `<$0.01` label. Storage retains the
-original precision.
-
 The Usage page's Model pricing dialog stores Profile-scoped USD prices per
 million ordinary input, output, cache read and cache write tokens. Provider and
 model IDs must match exactly; no cross-provider model-name fallback is used.
diff --git a/packages/client/src/utils/usage-cost.ts b/packages/client/src/utils/usage-cost.ts
index d6dc4c5eaa..7d910f4592 100644
--- a/packages/client/src/utils/usage-cost.ts
+++ b/packages/client/src/utils/usage-cost.ts
@@ -13,7 +13,5 @@ export function usageCostState(amount: number, coverage?: UsageCostCoverage, has
 export function formatUsageCost(amount: number, coverage?: UsageCostCoverage, hasActivity = true): string | null {
   if (usageCostState(amount, coverage, hasActivity) === 'unknown') return null
   if (amount === 0) return '$0.00'
-  if (amount < 0.000001) return '<$0.000001'
-  // Keep small token charges visible in both daily amounts and larger totals.
-  return `$${amount.toFixed(6).replace(/(\.\d{2,}?)0+$/, '$1')}`
+  return amount < 0.01 ? '<$0.01' : `$${amount.toFixed(2)}`
 }
diff --git a/tests/client/usage-cost.test.ts b/tests/client/usage-cost.test.ts
index 984c5693bd..9225ea8f7f 100644
--- a/tests/client/usage-cost.test.ts
+++ b/tests/client/usage-cost.test.ts
@@ -7,7 +7,7 @@ describe('usage cost presentation', () => {
     expect(formatUsageCost(0, { reported: 1, estimated: 0, unknown: 0 })).toBe('$0.00')
     expect(formatUsageCost(0)).toBeNull()
     expect(formatUsageCost(0, undefined, false)).toBe('$0.00')
-    expect(formatUsageCost(0.001)).toBe('$0.001')
+    expect(formatUsageCost(0.001)).toBe('<$0.01')
   })
   it('identifies partial coverage and estimates without losing the known amount', () => {
     const partial = { reported: 2, estimated: 1, unknown: 1 }
@@ -16,15 +16,4 @@ describe('usage cost presentation', () => {
     expect(usageCostState(1, { reported: 0, estimated: 1, unknown: 0 })).toBe('estimated')
     expect(usageCostState(1, { reported: 1, estimated: 1, unknown: 0 })).toBe('mixed')
   })
-
-  it('shows small charges changing the total instead of hiding both below one cent', () => {
-    const coverage = { reported: 0, estimated: 3, unknown: 9 }
-    expect(formatUsageCost(0.002887398, coverage)).toBe('$0.002887')
-    expect(formatUsageCost(0.004529376, coverage)).toBe('$0.004529')
-    expect(formatUsageCost(10.001641978, coverage)).toBe('$10.001642')
-    expect(formatUsageCost(0.000001, coverage)).toBe('$0.000001')
-    expect(formatUsageCost(0.0000001, coverage)).toBe('<$0.000001')
-    expect(formatUsageCost(10, coverage)).toBe('$10.00')
-    expect(formatUsageCost(0.1, coverage)).toBe('$0.10')
-  })
 })
diff --git a/tests/e2e/usage-cost.spec.ts b/tests/e2e/usage-cost.spec.ts
index fea0e40d5b..33a2c0554f 100644
--- a/tests/e2e/usage-cost.spec.ts
+++ b/tests/e2e/usage-cost.spec.ts
@@ -25,14 +25,6 @@ test('shows unknown, partial and free costs and saves explicit model pricing', a
   await page.getByRole('button', { name: 'Refresh', exact: true }).click()
   await expect(card.getByText('$0.25', { exact: true })).toBeVisible()
   await expect(card.getByText('Partial cost; some usage is unpriced')).toBeVisible()
-  coverage = { reported: 0, estimated: 1, unknown: 1 }; cost = 0.002887398
-  await page.getByRole('button', { name: 'Refresh', exact: true }).click()
-  await expect(card.getByText('$0.002887', { exact: true })).toBeVisible()
-  await expect(page.locator('tbody')).toContainText('$0.002887')
-  coverage = { reported: 0, estimated: 3, unknown: 1 }; cost = 0.004529376
-  await page.getByRole('button', { name: 'Refresh', exact: true }).click()
-  await expect(card.getByText('$0.004529', { exact: true })).toBeVisible()
-  await expect(page.locator('tbody')).toContainText('$0.004529')
   coverage = { reported: 1, estimated: 0, unknown: 0 }; cost = 0
   await page.getByRole('button', { name: 'Refresh', exact: true }).click()
   await expect(card.getByText('$0.00', { exact: true })).toBeVisible()

From 39838ac48f5bc68bbbcb6d1837a9f77e50fed7a2 Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Tue, 29 Sep 2026 22:40:28 +0800
Subject: [PATCH 6/8] fix context lookup for older GLM Coding Plan models

---
 docs/harness/usage-cost.md                    |  5 ++++
 .../modules/hermes/services/models/context.ts | 27 ++++++++++++++-----
 tests/server/model-catalog.test.ts            |  1 +
 tests/server/model-context.test.ts            | 21 +++++++++++++++
 4 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index 2054a7eb1a..a7c402985e 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -49,6 +49,11 @@ Studio's built-in `glm` points to the domestic GLM Coding Plan endpoint and maps
 to `zhipuai-coding-plan` for both pricing and context limits. It does not borrow
 `zai`/`zhipuai` metered API prices. A catalog plan rate of zero is retained as an
 estimate; it does not account for the subscription fee or imply a free plan.
+When a Coding Plan catalog omits an older model such as GLM-4.5, context/output
+limits and capabilities may fall back to that vendor's ordinary API catalog
+(`zhipuai-coding-plan` → `zhipuai`, `zai-coding-plan` → `zai`). Existing plan
+specifications and manual overrides take priority. This metadata fallback does
+not make the model available on the endpoint or supply metered API prices.
 
 Estimated records retain nullable `cost_pricing` JSON with the rate source,
 effective USD-per-million rates, catalog SHA-256 version, download time and
diff --git a/packages/server/src/modules/hermes/services/models/context.ts b/packages/server/src/modules/hermes/services/models/context.ts
index 4821b268b8..7657b69a00 100644
--- a/packages/server/src/modules/hermes/services/models/context.ts
+++ b/packages/server/src/modules/hermes/services/models/context.ts
@@ -75,6 +75,13 @@ const MODEL_CACHE_PROVIDER_ALIASES: Record<string, string[]> = {
   'xai-oauth': ['xai'],
 }
 
+// Coding Plan catalogs may omit older models. Only their own vendor can supply
+// missing model specifications; this fallback must never be used for pricing.
+const MODEL_METADATA_PROVIDER_FALLBACKS: Record<string, string> = {
+  'zhipuai-coding-plan': 'zhipuai',
+  'zai-coding-plan': 'zai',
+}
+
 // --- Config YAML helpers (js-yaml) ---
 
 function loadConfig(profileDir: string): any | null {
@@ -289,9 +296,15 @@ function findModelEntry(models: Record<string, ModelEntry>, modelName: string):
   return undefined
 }
 
-function lookupContextInProvider(provider: ProviderEntry | null, modelName: string): number | null {
-  const models = provider?.models || {}
-  return getCachedContext(findModelEntry(models, modelName))
+function findProviderModelEntry(data: Record<string, ProviderEntry>, provider: string, modelName: string): ModelEntry | undefined {
+  const own = findModelEntry(getProviderEntry(data, provider)?.models || {}, modelName)
+  if (own) return own
+  for (const candidate of getProviderCandidates(provider)) {
+    const fallback = MODEL_METADATA_PROVIDER_FALLBACKS[candidate]
+    if (!fallback) continue
+    const entry = findModelEntry(getProviderEntry(data, fallback)?.models || {}, modelName)
+    if (entry) return entry
+  }
 }
 
 function lookupContextGloballyByModelName(data: Record<string, ProviderEntry>, modelName: string): number | null {
@@ -364,7 +377,7 @@ function lookupContextFromCache(config: any, modelName: string, provider: string
       const inferredProvider = resolveCustomCacheProvider(config, modelName, provider)
 
       if (inferredProvider) {
-        const scoped = lookupContextInProvider(getProviderEntry(data, inferredProvider), modelName)
+        const scoped = getCachedContext(findProviderModelEntry(data, inferredProvider, modelName))
         if (scoped) return scoped
         return null
       }
@@ -376,7 +389,7 @@ function lookupContextFromCache(config: any, modelName: string, provider: string
       return null
     }
 
-    return lookupContextInProvider(getProviderEntry(data, provider), modelName)
+    return getCachedContext(findProviderModelEntry(data, provider, modelName))
   }
 
   // Legacy configs may omit model.provider; preserve the old global exact/CI lookup semantics.
@@ -472,7 +485,7 @@ export function getModelRuntimeCapabilities(input: ModelContextLengthOptions): {
       const profileDir = getProfileDir(input.profile)
       const config = loadConfig(profileDir)
       const inferredProvider = resolveCustomCacheProvider(config, model, provider)
-      if (inferredProvider) entry = findModelEntry(getProviderEntry(data, inferredProvider)?.models || {}, model)
+      if (inferredProvider) entry = findProviderModelEntry(data, inferredProvider, model)
       else if (provider === 'custom') {
         for (const candidate of Object.values(data)) {
           const found = findModelEntry(candidate.models || {}, model)
@@ -485,7 +498,7 @@ export function getModelRuntimeCapabilities(input: ModelContextLengthOptions): {
         }
       }
     } else if (provider) {
-      entry = findModelEntry(getProviderEntry(data, provider)?.models || {}, model)
+      entry = findProviderModelEntry(data, provider, model)
     } else {
       for (const candidate of Object.values(data)) {
         entry = findModelEntry(candidate.models || {}, model)
diff --git a/tests/server/model-catalog.test.ts b/tests/server/model-catalog.test.ts
index 3683007b82..28fca7b0d6 100644
--- a/tests/server/model-catalog.test.ts
+++ b/tests/server/model-catalog.test.ts
@@ -134,6 +134,7 @@ describe('catalog cost estimates', () => {
       costUsd: 0, costSource: 'estimated', costPricing: { rates: { provider: 'zhipuai-coding-plan' } },
     })
     expect(estimateCatalogUsageCost(snapshot({ zai: data.zai }), 'glm', 'glm-5.3-flash', usage)).toBeUndefined()
+    expect(estimateCatalogUsageCost(snapshot({ zhipuai: data.zai }), 'glm', 'glm-5.3-flash', usage)).toBeUndefined()
     expect(estimateCatalogUsageCost(snapshot(data), 'custom:glm', 'glm-5.3-flash', usage)).toBeUndefined()
   })
 })
diff --git a/tests/server/model-context.test.ts b/tests/server/model-context.test.ts
index 9c091d9bf9..6ffec5794c 100644
--- a/tests/server/model-context.test.ts
+++ b/tests/server/model-context.test.ts
@@ -109,6 +109,7 @@ describe('getModelContextLength', () => {
     writeConfig('model:\n  default: glm-5.3-flash\n  provider: glm\n')
     writeModelsCache({
       'zhipuai-coding-plan': { models: { 'glm-5.3-flash': { limit: { context: 1_000_000, output: 131_072 } } } },
+      zhipuai: { models: { 'glm-5.3-flash': { limit: { context: 400_000, output: 64_000 } } } },
       zai: { models: { 'glm-5.3-flash': { limit: { context: 200_000, output: 32_000 } } } },
     })
     const { getModelContextLength, getModelRuntimeCapabilities } = await loadModelContext()
@@ -117,6 +118,26 @@ describe('getModelContextLength', () => {
       .toMatchObject({ contextWindow: 1_000_000, outputLimit: 131_072 })
   })
 
+  it.each([
+    ['glm', 'zhipuai-coding-plan', 'zhipuai'],
+    ['zhipuai-coding-plan', 'zhipuai-coding-plan', 'zhipuai'],
+    ['glm-coding-plan', 'zai-coding-plan', 'zai'],
+    ['zai-coding-plan', 'zai-coding-plan', 'zai'],
+  ])('uses vendor specifications for an older model absent from the %s catalog', async (provider, plan, vendor) => {
+    writeConfig(`model:\n  default: glm-4.5\n  provider: ${provider}\n`)
+    writeModelsCache({
+      [plan]: { models: { 'glm-5.3-flash': { limit: { context: 1_000_000, output: 131_072 } } } },
+      [vendor]: { models: { 'glm-4.5': { limit: { context: 131_072, output: 98_304 }, reasoning: true, modalities: { input: ['text'] } } } },
+    })
+    const { getModelContextLength, getModelRuntimeCapabilities } = await loadModelContext()
+    expect(getModelContextLength()).toBe(131_072)
+    expect(getModelRuntimeCapabilities({ provider, model: 'glm-4.5' }))
+      .toEqual({ contextWindow: 131_072, outputLimit: 98_304, reasoning: true, input: ['text'] })
+    expect(getModelContextLength({ provider: 'custom:relay', model: 'glm-4.5' })).toBe(256_000)
+    writeConfig(`model:\n  default: glm-4.5\n  provider: ${provider}\n  context_length: 80000\n`)
+    expect(getModelContextLength()).toBe(80_000)
+  })
+
   it('uses a caller-provided fallback only when no model context is configured', async () => {
     writeConfig(`model:\n  default: grok-4.6\n  provider: custom:grok\n`)
 

From d67c03d2ea2e90382648b8438d03b1c27f6ef65c Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Wed, 30 Sep 2026 05:50:43 +0800
Subject: [PATCH 7/8] fix tier pricing for aggregate subtask usage

---
 docs/harness/usage-cost.md                    |  4 ++-
 .../chat-run/handle-ekko-agent-run.ts         |  2 +-
 .../studio/services/usage/catalog-pricing.ts  |  3 ++-
 tests/server/model-catalog.test.ts            | 15 +++++++++++
 tests/server/run-chat-ekko-context.test.ts    |  2 +-
 tests/server/usage-cost.test.ts               | 25 +++++++++++++++++++
 6 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index a7c402985e..7f897377f1 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -42,7 +42,9 @@ prices are reference estimates, not a relay invoice, subscription charge or
 account-specific discount; configure custom rates when appropriate. Missing
 rates for used token categories leave cost unknown. Context tiers include cache
 tokens; a run aggregate above a tier threshold stays unknown unless it represents
-a single API call. Explicit tiers take precedence over legacy `context_over_200k`.
+a single API call. Ekko subtask totals use run scope; an explicit call count takes
+precedence over scope when determining whether tier pricing is safe. Explicit
+tiers take precedence over legacy `context_over_200k`.
 Separate reasoning rates replace the reasoning portion of the output charge.
 
 Studio's built-in `glm` points to the domestic GLM Coding Plan endpoint and maps
diff --git a/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts b/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts
index 1a5b115741..1a2350c4a8 100644
--- a/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts
+++ b/packages/server/src/modules/studio/services/chat-run/handle-ekko-agent-run.ts
@@ -1122,7 +1122,7 @@ export async function handleEkkoAgentRun(
             runId: `${event.runId}:subagent:${event.subagentId}`,
             source: 'ekko_agent',
             agent: 'ekko_agent',
-            usageScope: 'model_call',
+            usageScope: 'run',
             purpose: event.background ? 'ekko-background-subtask' : 'ekko-subtask',
             apiCalls: event.apiCalls,
             usage: {
diff --git a/packages/server/src/modules/studio/services/usage/catalog-pricing.ts b/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
index 2a9b0bcfa0..e1983d2ce9 100644
--- a/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
+++ b/packages/server/src/modules/studio/services/usage/catalog-pricing.ts
@@ -32,6 +32,7 @@ export function estimateCatalogUsageCost(
   let selected = { ...cost }
   let contextThreshold: number | undefined
   const prompt = usage.inputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+  const isSingleCall = apiCalls === 1 || (apiCalls === undefined && scope === 'model_call')
   let tiers: Array<{ threshold: number; rates: Record<string, unknown> }> = []
   if (cost.tiers !== undefined) {
     if (!Array.isArray(cost.tiers)) return
@@ -50,7 +51,7 @@ export function estimateCatalogUsageCost(
   for (const tier of tiers.sort((a, b) => a.threshold - b.threshold)) {
     if (prompt <= tier.threshold) continue
     // A whole-run token sum cannot reveal which individual requests crossed a pricing tier.
-    if (scope !== 'model_call' && apiCalls !== 1) return
+    if (!isSingleCall) return
     selected = { ...selected, ...tier.rates }
     contextThreshold = tier.threshold
   }
diff --git a/tests/server/model-catalog.test.ts b/tests/server/model-catalog.test.ts
index 28fca7b0d6..805cfd92eb 100644
--- a/tests/server/model-catalog.test.ts
+++ b/tests/server/model-catalog.test.ts
@@ -94,6 +94,21 @@ describe('catalog cost estimates', () => {
     expect(estimateCatalogUsageCost(snapshot(), 'openai', 'model', large, 'run', 1)?.costPricing?.contextThreshold).toBe(200_000)
   })
 
+  it.each(['explicit', 'legacy'])('does not apply %s tier rates to multi-call usage labeled as a model call', kind => {
+    const data: any = catalog()
+    if (kind === 'legacy') {
+      data.openai.models.model.cost.context_over_200k = { input: 4, output: 12 }
+      delete data.openai.models.model.cost.tiers
+    }
+    const single = { inputTokens: 150_000, outputTokens: 1000, cacheReadTokens: 0, cacheWriteTokens: 0 }
+    const aggregate = { ...single, inputTokens: 300_000, outputTokens: 2000 }
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', single, 'model_call', 1)?.costUsd).toBeCloseTo(0.308)
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', aggregate, 'model_call', 2)).toBeUndefined()
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', aggregate, 'run', 2)).toBeUndefined()
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', aggregate, 'model_call', 1)?.costPricing?.contextThreshold).toBe(200_000)
+    expect(estimateCatalogUsageCost(snapshot(data), 'openai', 'model', single, 'run', 2)?.costUsd).toBeCloseTo(0.308)
+  })
+
   it('handles legacy context pricing without confusing a newer explicit tier with the legacy 200k name', () => {
     const data: any = catalog()
     data.openai.models.model.cost.tiers[0].tier.size = 272_000
diff --git a/tests/server/run-chat-ekko-context.test.ts b/tests/server/run-chat-ekko-context.test.ts
index 79808588aa..a595ded5c8 100644
--- a/tests/server/run-chat-ekko-context.test.ts
+++ b/tests/server/run-chat-ekko-context.test.ts
@@ -1037,7 +1037,7 @@ describe('ekko-agent context usage events', () => {
       runId: 'run-parent:subagent:child-background',
       source: 'ekko_agent',
       agent: 'ekko_agent',
-      usageScope: 'model_call',
+      usageScope: 'run',
       purpose: 'ekko-background-subtask',
       apiCalls: 2,
       usage: {
diff --git a/tests/server/usage-cost.test.ts b/tests/server/usage-cost.test.ts
index 0b5c777c98..b9ba924925 100644
--- a/tests/server/usage-cost.test.ts
+++ b/tests/server/usage-cost.test.ts
@@ -163,6 +163,31 @@ describe('usage cost accounting', () => {
     expect(catalogMock.refreshModelCatalog).not.toHaveBeenCalled()
   })
 
+  it.each([false, true])('keeps ambiguous subtask costs unknown while retaining reported and manual costs (cold start: %s)', async cold => {
+    const tieredCatalog = { ...catalogSnapshot, data: { global: { models: {
+      'test-model': { cost: { input: 2, output: 8, tiers: [
+        { input: 4, output: 12, tier: { type: 'context', size: 200_000 } },
+      ] } },
+    } } } }
+    if (cold) catalogMock.refreshModelCatalog.mockResolvedValue(tieredCatalog)
+    else catalogMock.getModelCatalogSnapshot.mockReturnValue(tieredCatalog)
+    const usage = { inputTokens: 300_000, outputTokens: 2000 }
+    const subtask = { source: 'ekko_agent', agent: 'ekko_agent', usageScope: 'model_call', apiCalls: 2 }
+    record('subtask', usage, subtask)
+    await Promise.resolve()
+    const saved = db.prepare('SELECT cost_usd, cost_source, cost_pricing, api_calls FROM session_usage').get()
+    expect(saved).toMatchObject({ cost_usd: null, cost_source: 'unknown', cost_pricing: null, api_calls: 2 })
+    expect(catalogMock.refreshModelCatalog).toHaveBeenCalledTimes(cold ? 1 : 0)
+
+    record('reported-subtask', { ...usage, cost: 0.5 }, subtask)
+    saveUsagePricing('p', [{ provider: 'global', model: 'test-model', input: 1, output: 2 }])
+    record('manual-subtask', usage, subtask)
+    expect(getLocalUsageStats('p', 1)).toMatchObject({
+      cost: 0.804, input_tokens: 900_000, output_tokens: 6000, total_api_calls: 6,
+      cost_coverage: { reported: 1, estimated: 1, unknown: 1 },
+    })
+  })
+
   it('late enrichment cannot overwrite a known cost or restore a deleted row', () => {
     const ref = updateUsage('one', { inputTokens: 10, outputTokens: 1 })!
     fillMissingUsageCost(ref, { costUsd: 0, costSource: 'reported' })

From 0892e4d1196e99f932f9af4ceef70b041112b21a Mon Sep 17 00:00:00 2001
From: ekko <fqsy1416@gmail.com>
Date: Wed, 30 Sep 2026 06:35:13 +0800
Subject: [PATCH 8/8] preserve subtask tokens in live activity usage

---
 docs/harness/usage-cost.md                    |  2 ++
 .../repositories/live-activity-usage.ts       |  9 +++--
 tests/server/live-activity-usage.test.ts      | 33 +++++++++++++++++--
 3 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/docs/harness/usage-cost.md b/docs/harness/usage-cost.md
index 7f897377f1..28753ad13d 100644
--- a/docs/harness/usage-cost.md
+++ b/docs/harness/usage-cost.md
@@ -46,6 +46,8 @@ a single API call. Ekko subtask totals use run scope; an explicit call count tak
 precedence over scope when determining whether tier pricing is safe. Explicit
 tiers take precedence over legacy `context_over_200k`.
 Separate reasoning rates replace the reasoning portion of the output charge.
+App Live Activity token totals include these disjoint Ekko subtask records along
+with individual model calls, while excluding other run summaries and estimates.
 
 Studio's built-in `glm` points to the domestic GLM Coding Plan endpoint and maps
 to `zhipuai-coding-plan` for both pricing and context limits. It does not borrow
diff --git a/packages/server/src/modules/studio/repositories/live-activity-usage.ts b/packages/server/src/modules/studio/repositories/live-activity-usage.ts
index ccac41d42f..df37eac224 100644
--- a/packages/server/src/modules/studio/repositories/live-activity-usage.ts
+++ b/packages/server/src/modules/studio/repositories/live-activity-usage.ts
@@ -1,8 +1,9 @@
 import { getDb } from '../infrastructure/database'
 import { USAGE_TABLE } from '../infrastructure/database/schemas'
 
-/** Recorded model-call usage in this activity's time window, not session lifetime totals.
- * Exclude estimates and run-level summaries to avoid double-counting model calls.
+/** Recorded usage in this activity's time window, not session lifetime totals.
+ * Ekko subtask totals are disjoint: their individual calls are not recorded here.
+ * Exclude estimates and other run-level summaries to avoid double-counting model calls.
  * Unknown/unavailable data is absent, never a fabricated zero.
  */
 export function getLiveActivityUsage(sessionId: string, profile: string, startedAtEpoch: number, throughMs: number) {
@@ -12,7 +13,9 @@ export function getLiveActivityUsage(sessionId: string, profile: string, started
   if (!db) return undefined
   try {
     const row = db.prepare(`SELECT COUNT(*) AS count, SUM(input_tokens) AS input, SUM(output_tokens) AS output
-      FROM ${USAGE_TABLE} WHERE session_id=? AND profile=? AND usage_scope='model_call'
+      FROM ${USAGE_TABLE} WHERE session_id=? AND profile=?
+      AND (usage_scope='model_call' OR (usage_scope='run' AND source='ekko_agent'
+        AND purpose IN ('ekko-subtask', 'ekko-background-subtask')))
       AND is_estimated=0 AND created_at>=? AND created_at<=?`).get(sessionId, profile, startedAtEpoch * 1000, throughMs) as any
     if (!row || !Number(row.count)) return undefined
     const inputTokens = Number(row.input), outputTokens = Number(row.output)
diff --git a/tests/server/live-activity-usage.test.ts b/tests/server/live-activity-usage.test.ts
index d3099ba4cb..bbcd93fc75 100644
--- a/tests/server/live-activity-usage.test.ts
+++ b/tests/server/live-activity-usage.test.ts
@@ -5,9 +5,9 @@ describe('Live Activity recorded usage window',()=>{
  it('excludes historical/future calls, other accounts profiles/sessions, estimates and run summaries',async()=>{
   const db=new DatabaseSync(':memory:')
   vi.doMock('../../packages/server/src/modules/studio/infrastructure/database/index',()=>({getDb:()=>db}))
-  const {USAGE_TABLE}=await import('../../packages/server/src/modules/studio/infrastructure/database/schemas')
-  db.exec(`CREATE TABLE ${USAGE_TABLE}(session_id TEXT,profile TEXT,usage_scope TEXT,is_estimated INTEGER,created_at INTEGER,input_tokens INTEGER,output_tokens INTEGER)`)
-  const add=db.prepare(`INSERT INTO ${USAGE_TABLE} VALUES(?,?,?,?,?,?,?)`)
+  const {USAGE_TABLE,USAGE_SCHEMA}=await import('../../packages/server/src/modules/studio/infrastructure/database/schemas')
+  db.exec(`CREATE TABLE ${USAGE_TABLE} (${Object.entries(USAGE_SCHEMA).map(([key, sql]) => `${key} ${sql}`).join(',')})`)
+  const add=db.prepare(`INSERT INTO ${USAGE_TABLE}(session_id,profile,usage_scope,is_estimated,created_at,input_tokens,output_tokens) VALUES(?,?,?,?,?,?,?)`)
   add.run('s','p','model_call',0,10000,20,3);add.run('s','p','model_call',0,11000,30,4)
   for(const row of [['s','p','model_call',0,9000],['s','p','model_call',0,13000],['s','other','model_call',0,10000],['other','p','model_call',0,10000],['s','p','model_call',1,10000],['s','p','run',0,10000]])add.run(...row,999,999)
   const {getLiveActivityUsage}=await import('../../packages/server/src/modules/studio/repositories/live-activity-usage')
@@ -16,4 +16,31 @@ describe('Live Activity recorded usage window',()=>{
   expect(getLiveActivityUsage('s','p',NaN,12000)).toBeUndefined()
   db.close();vi.doUnmock('../../packages/server/src/modules/studio/infrastructure/database/index');vi.resetModules()
  })
+
+ it('includes disjoint Ekko subtask totals without including other run summaries',async()=>{
+  const db=new DatabaseSync(':memory:')
+  vi.doMock('../../packages/server/src/modules/studio/infrastructure/database/index',()=>({getDb:()=>db}))
+  try {
+   const {USAGE_TABLE,USAGE_SCHEMA}=await import('../../packages/server/src/modules/studio/infrastructure/database/schemas')
+   db.exec(`CREATE TABLE ${USAGE_TABLE} (${Object.entries(USAGE_SCHEMA).map(([key, sql]) => `${key} ${sql}`).join(',')})`)
+   const add=db.prepare(`INSERT INTO ${USAGE_TABLE}(session_id,profile,usage_scope,source,purpose,is_estimated,created_at,input_tokens,output_tokens) VALUES(?,?,?,?,?,?,?,?,?)`)
+   add.run('s','p','model_call','ekko_agent','',0,10000,20,3)
+   add.run('s','p','model_call','ekko_agent','ekko-subtask',0,10000,7,1)
+   add.run('s','p','run','ekko_agent','ekko-subtask',0,11000,30,4)
+   add.run('s','p','run','ekko_agent','ekko-background-subtask',0,12000,40,5)
+   for(const row of [
+    ['s','p','run','ekko_agent','',0,10000],
+    ['s','p','run','coding_agent','ekko-subtask',0,10000],
+    ['s','p','run','ekko_agent','ekko-subtask',1,10000],
+    ['s','p','run','ekko_agent','ekko-subtask',0,9000],
+    ['s','p','run','ekko_agent','ekko-background-subtask',0,13000],
+    ['s','other','run','ekko_agent','ekko-subtask',0,10000],
+    ['other','p','run','ekko_agent','ekko-background-subtask',0,10000],
+   ])add.run(...row,999,999)
+   const {getLiveActivityUsage}=await import('../../packages/server/src/modules/studio/repositories/live-activity-usage')
+   expect(getLiveActivityUsage('s','p',10,12000)).toEqual({inputTokens:97,outputTokens:13})
+  } finally {
+   db.close();vi.doUnmock('../../packages/server/src/modules/studio/infrastructure/database/index');vi.resetModules()
+  }
+ })
 })