fix(desktop,storage): keep the usage rings honest about what they sum

Second review round, all under the ring math rather than its shape.

The token split clamped cacheRead to input, but the ledger keeps the
provider's cached share unclamped when no prompt total was reported, so
`cacheRead > input` is a normal aggregate — 200k cached tokens with zero
prompt became a zero segment. The split now reads cacheRead as reported;
`uncachedInput` already floors the other way, and the total remains the
sum of the drawn segments.

The time split decided presence through `totalDurationMs ?? 0`, which
made a host that measured zero model time drop its row and its call
count while the tool row survived on count. `totalDurationMs` is now a
required summary key — the epoch bump already refuses peers that predate
it, so the optional decoder path and its test were unreachable — and the
split decides presence on the reported fields before filtering. The ring
label says "Recorded Time": the figures are sums of per-call durations,
not wall clock, and parallel or nested calls overlap.

`toolUsage` stays optional for a data reason instead of a version one:
tool rows predate connection attribution, so a `connectionSlug`-scoped
query cannot answer the tool ledger honestly. The Host omits the split
for that query rather than persist a slug that would only cover new rows
and let history silently vanish under the filter.

Every tool read now shares one row filter, so tool buckets honour the
same Session, provider, and model filters the summary applies — they
previously ignored Session identity. And the ts range moves into the
invocation query: the ledger has no retention, and the unbounded decode
ran on every summary refresh; the `(ts DESC, id)` index answers it.

Generated-by: ZCode

Author: bowenliang123

apps/desktop/src/main/__tests__/runtime-host-usage-ipc-main.test.ts

@@ -56,6 +56,7 @@ test("settings usage stats use the canonical model-call total and load every act
               cacheHitRequests: 10,
               cacheCreateRequests: 5,
               errorRequests: 2,
+              totalDurationMs: 0,
             },
             provenance: provenance(),
           } satisfies UsageQueryResult;
@@ -176,6 +177,7 @@ test("settings usage stats reject a non-advancing activity page", async () => {
               cacheHitRequests: 0,
               cacheCreateRequests: 0,
               errorRequests: 0,
+              totalDurationMs: 0,
             },
             provenance: provenance(),
           } satisfies UsageQueryResult;
@@ -243,6 +245,7 @@ test("settings usage stats degrade instead of erroring when logs disagree with t
               cacheHitRequests: 0,
               cacheCreateRequests: 0,
               errorRequests: 0,
+              totalDurationMs: 0,
             },
             provenance: provenance(),
           } satisfies UsageQueryResult;
@@ -316,6 +319,7 @@ test("settings usage stats group the provider breakdown by connection", async ()
               cacheHitRequests: 0,
               cacheCreateRequests: 0,
               errorRequests: 0,
+              totalDurationMs: 0,
             },
             provenance: provenance(),
           } satisfies UsageQueryResult;
@@ -394,6 +398,7 @@ test("settings usage stats truncate the activity log at the cap instead of error
               cacheHitRequests: 0,
               cacheCreateRequests: 0,
               errorRequests: 0,
+              totalDurationMs: 0,
             },
             provenance: provenance(),
           } satisfies UsageQueryResult;
@@ -467,6 +472,7 @@ test("settings usage stats name each row from the Host-resolved session title",
               cacheHitRequests: 0,
               cacheCreateRequests: 0,
               errorRequests: 0,
+              totalDurationMs: 0,
             },
             provenance: provenance(),
           } satisfies UsageQueryResult;

apps/desktop/src/main/__tests__/session-inspector-panel-model.test.ts

@@ -50,6 +50,7 @@ test('does not render legacy zero cost as a known free Session', () => {
     cacheHitRequests: 0,
     cacheCreateRequests: 0,
     errorRequests: 0,
+    totalDurationMs: 0,
     provenance: {
       coverage: {
         attempts: 0,
@@ -85,6 +86,7 @@ test('reports incomplete provenance as unavailable regardless of recorded reques
     cacheHitRequests: 0,
     cacheCreateRequests: 0,
     errorRequests: 0,
+    totalDurationMs: 0,
     provenance: {
       coverage: {
         attempts: 0,
@@ -121,6 +123,7 @@ test('does not estimate a cache-hit ratio from partial usage', () => {
     cacheHitRequests: 1,
     cacheCreateRequests: 0,
     errorRequests: 0,
+    totalDurationMs: 0,
     provenance: {
       coverage: {
         attempts: 1,

apps/desktop/src/main/__tests__/session-inspector-usage-stats.test.ts

@@ -44,6 +44,7 @@ function usageSummary(overrides: Partial<UsageSummaryV2> = {}): UsageSummaryV2 {
     cacheHitRequests: 2,
     cacheCreateRequests: 0,
     errorRequests: 0,
+    totalDurationMs: 0,
     ...overrides,
   };
 }
@@ -183,15 +184,61 @@ test('splits recorded time between model calls and tool executions', () => {
   assert.equal(durationUsage?.totalDurationMs, 1_873_000 + 78_000);
 });
 
-test('a host from before duration reporting shows no time split rather than zeros', () => {
-  const { durationUsage } = deriveInspectorOverviewModel(undefined, usageSummary());
+test('keeps a cache-read share the provider reported without a prompt total', () => {
+  // Core leaves the ledger's cacheRead unclamped when no prompt total was
+  // reported, so cacheRead > input is a normal aggregate there — clamping it
+  // to input would erase exactly the sessions the split exists to describe.
+  const { tokenUsage } = deriveInspectorOverviewModel(
+    undefined,
+    usageSummary({
+      totalTokens: {
+        input: 0,
+        output: 100,
+        cacheMiss: 60_000,
+        cacheRead: 200_000,
+        cacheWrite: 0,
+        reasoning: 0,
+        total: 260_100,
+      },
+    }),
+  );
+
+  assert.deepEqual(
+    tokenUsage?.segments.map((segment) => [segment.kind, segment.tokens]),
+    [
+      ['cacheRead', 200_000],
+      ['cacheMiss', 60_000],
+      ['output', 100],
+    ],
+  );
+  assert.equal(tokenUsage?.total, 260_100);
+});
+
+test('a host that measured zero model time keeps its row and its call count', () => {
+  // Presence follows the reported field, not a zero-derived default: zero is
+  // a measurement, and the row carries the count the model totals show too.
+  const { durationUsage } = deriveInspectorOverviewModel(
+    undefined,
+    usageSummary({ totalDurationMs: 0 }),
+  );
+  assert.deepEqual(
+    durationUsage?.segments.map((segment) => [segment.kind, segment.count, segment.durationMs]),
+    [['model', 3, 0]],
+  );
+});
+
+test('a row with neither a clock nor a count is dropped', () => {
+  const { durationUsage } = deriveInspectorOverviewModel(
+    undefined,
+    usageSummary({ totalRequests: 0, totalDurationMs: 0 }),
+  );
   assert.equal(durationUsage, undefined);
 });
 
 test('a tool row without a recorded duration still reports its count', () => {
   const { durationUsage } = deriveInspectorOverviewModel(
     undefined,
-    usageSummary({ totalRequests: 2, toolUsage: { requests: 4, durationMs: 0 } }),
+    usageSummary({ totalRequests: 0, totalDurationMs: 0, toolUsage: { requests: 4, durationMs: 0 } }),
   );
 
   assert.deepEqual(

apps/desktop/src/main/__tests__/use-session-trace.test.ts

@@ -79,6 +79,7 @@ function usageSummary(
     cacheHitRequests: 0,
     cacheCreateRequests: 0,
     errorRequests: 0,
+    totalDurationMs: 0,
     provenance: {
       coverage: {
         attempts: totalRequests,

apps/desktop/src/renderer/features/workbar/tools/inspector/session-inspector-overview-model.ts

@@ -149,8 +149,9 @@ export interface InspectorOverviewModel {
   tokenUsage?: InspectorTokenUsage;
   /**
    * Where the session's recorded time went, model calls against tool
-   * executions. Absent when the connected Runtime Host predates duration
-   * reporting or nothing was recorded — an unknown split is not a zero split.
+   * executions. Absent when the query could not answer either ledger — a
+   * connection-scoped query omits the tool side, and a session with no
+   * recorded time has no split to draw.
    */
   durationUsage?: InspectorDurationUsage;
 }
@@ -181,7 +182,11 @@ export interface InspectorDurationUsageSegment {
 }
 
 export interface InspectorDurationUsage {
-  /** model + tool recorded time — the active time this panel can account for. */
+  /**
+   * model + tool recorded time. A sum of per-call durations, not wall-clock:
+   * parallel settlements and nested calls overlap, so this can exceed the
+   * session's elapsed time.
+   */
   totalDurationMs: number;
   segments: readonly InspectorDurationUsageSegment[];
 }
@@ -256,17 +261,19 @@ function usageCacheHitRate(usage: SessionUsageSummary | undefined): number | und
  * from the ledger: several providers report the cached share only, and a
  * ledger zero there would understate the uncached input the session paid for.
  * The ledger's own `cacheMiss` is kept as a floor for records that reported
- * the miss but no prompt total. Output is the metered figure as billed —
- * providers that itemize reasoning include it in it, which is what the
- * panel's row label says.
+ * the miss but no prompt total. `cacheRead` is taken as reported — providers
+ * that itemize the cached share without a prompt total leave it larger than
+ * `input`, and clamping it here would erase exactly the sessions the split
+ * exists to describe. Output is the metered figure as billed — providers that
+ * itemize reasoning include it in it, which is what the panel's row label says.
  */
 function usageTokenSplit(usage: SessionUsageSummary | undefined): InspectorTokenUsage | undefined {
   if (!usage) return undefined;
   const { input, output, cacheRead, cacheMiss } = usage.totalTokens;
   if (input + output <= 0) return undefined;
   const uncachedInput = Math.max(input - cacheRead, cacheMiss, 0);
   const segments = [
-    { kind: 'cacheRead' as const, tokens: Math.min(cacheRead, input) },
+    { kind: 'cacheRead' as const, tokens: cacheRead },
     { kind: 'cacheMiss' as const, tokens: uncachedInput },
     { kind: 'output' as const, tokens: output },
   ].filter((segment) => segment.tokens > 0);
@@ -281,9 +288,11 @@ function usageTokenSplit(usage: SessionUsageSummary | undefined): InspectorToken
 
 /**
  * Model-call time against tool-execution time, both session-wide from their
- * own ledgers. Tool rows without a recorded duration contribute a request to
- * the count and nothing to the clock; a split nobody measured is not a split
- * worth drawing.
+ * own ledgers. Presence follows the reported fields, not a zero default: a
+ * host that measured zero model time keeps its row — the call count is real —
+ * and `toolUsage` is simply absent when the query could not be scoped. A row
+ * with neither a clock nor a count is dropped; a split nobody measured is not
+ * a split worth drawing.
  */
 function usageDurationSplit(
   usage: SessionUsageSummary | undefined,
@@ -294,13 +303,19 @@ function usageDurationSplit(
       {
         kind: 'model' as const,
         count: usage.totalRequests,
-        durationMs: usage.totalDurationMs ?? 0,
+        durationMs: usage.totalDurationMs,
       },
-      { kind: 'tool' as const, count: usage.toolUsage?.requests ?? 0, durationMs: usage.toolUsage?.durationMs ?? 0 },
+      ...(usage.toolUsage
+        ? [
+            {
+              kind: 'tool' as const,
+              count: usage.toolUsage.requests,
+              durationMs: usage.toolUsage.durationMs,
+            },
+          ]
+        : []),
     ] satisfies InspectorDurationUsageSegment[]
-  ).filter(
-    (segment) => segment.durationMs > 0 || (segment.kind === 'tool' && segment.count > 0),
-  );
+  ).filter((segment) => segment.durationMs > 0 || segment.count > 0);
   if (segments.length === 0) return undefined;
   return {
     totalDurationMs: segments.reduce((carry, segment) => carry + segment.durationMs, 0),

apps/desktop/src/renderer/locales/conversation-copy.ts

@@ -611,7 +611,7 @@ const COPY = {
       },
       durationUsage: {
         title: '耗时统计',
-        center: '活跃时间',
+        center: '记录时长',
         segment: {
           model: (count) => `LLM 调用 × ${count}`,
           tool: (count) => `工具执行 × ${count}`,
@@ -867,7 +867,7 @@ const COPY = {
       },
       durationUsage: {
         title: 'Time breakdown',
-        center: 'Active Time',
+        center: 'Recorded Time',
         segment: {
           model: (count) => `LLM Calls × ${count}`,
           tool: (count) => `Tool Runs × ${count}`,

packages/core/src/__tests__/usage-ledger-merge.test.ts

@@ -81,6 +81,7 @@ function legacySummary(overrides: Partial<UsageSummaryV2> = {}): UsageSummaryV2
     cacheHitRequests: 0,
     cacheCreateRequests: 0,
     errorRequests: 1,
+    totalDurationMs: 0,
     ...overrides,
   };
 }
@@ -157,9 +158,8 @@ describe('usage ledger merge', () => {
     );
     assert.equal(merged.totalDurationMs, 1_200);
 
-    // A legacy store from before the field existed contributes nothing to the
-    // sum rather than an unknown that would take the canonical half down with
-    // it — the projection always measures the attempts it counts.
+    // The projection always measures the attempts it counts; a legacy store
+    // with no recorded time simply contributes a zero to the sum.
     const canonicalOnly = mergeUsageSummary(
       legacySummary(),
       {

packages/core/src/usage-ledger-merge.ts

@@ -158,9 +158,9 @@ export function mergeUsageSummary(
     range: projected.range,
     totalRequests: legacy.totalRequests + projected.totalRequests,
     totalCostUsd: legacy.totalCostUsd + projected.totalCostUsd,
-    // The projection always measures the attempts it counted; a legacy store
-    // from before the field simply contributes nothing to the sum.
-    totalDurationMs: (legacy.totalDurationMs ?? 0) + projected.totalDurationMs,
+    // The projection always measures the attempts it counted, and every legacy
+    // summary carries the same field.
+    totalDurationMs: legacy.totalDurationMs + projected.totalDurationMs,
     totalTokens: {
       input: legacy.totalTokens.input + projected.totalTokens.input,
       output: legacy.totalTokens.output + projected.totalTokens.output,

packages/core/src/usage-stats/types.ts

@@ -66,15 +66,18 @@ export interface UsageSummaryV2 {
   /**
    * Recorded model-call time, summed over the same rows as `totalTokens`.
    *
-   * Optional because it postdates the summary's first consumers: a Runtime Host
-   * that has not been upgraded omits it rather than reporting a zero it never
-   * measured. Absent means unknown, not free of latency.
+   * Every summary writes it, and the protocol epoch refuses peers that predate
+   * it at the handshake, so a total without a time basis cannot cross the wire.
    */
-  totalDurationMs?: number;
+  totalDurationMs: number;
   /**
    * Recorded tool executions behind the same query, from the tool-invocation
    * ledger — the model-call ledger does not describe them, so there is no
    * canonical source to merge and this comes from the store alone.
+   *
+   * Optional because tool rows that predate connection attribution cannot
+   * answer a `connectionSlug` filter honestly: the Host omits the split for
+   * that query rather than drawing a ring from rows it cannot scope.
    */
   toolUsage?: { requests: number; durationMs: number };
 }

packages/runtime-host/src/__tests__/usage-pricing-protocol.test.ts

@@ -330,10 +330,9 @@ describe('Usage/Pricing protocol', () => {
     }
   });
 
-  test('a summary carries duration totals as optional figures, not required zeros', () => {
-    // Newer hosts report recorded call time and tool-execution totals; a host
-    // from before them still encodes, because "absent" means unknown rather
-    // than a measured zero.
+  test('a summary always carries its recorded time; only the tool split is optional', () => {
+    // The epoch bump makes the duration basis a handshake requirement, so a
+    // summary without one is not an older host — it is a malformed frame.
     assert.doesNotThrow(() =>
       usageResponse({
         kind: 'summary',
@@ -345,6 +344,22 @@ describe('Usage/Pricing protocol', () => {
         provenance: validProvenance(),
       }),
     );
+    assert.doesNotThrow(() =>
+      usageResponse({
+        kind: 'summary',
+        summary: validSummary(),
+        provenance: validProvenance(),
+      }),
+    );
+    assert.throws(
+      () =>
+        usageResponse({
+          kind: 'summary',
+          summary: { ...validSummary(), totalDurationMs: undefined },
+          provenance: validProvenance(),
+        }),
+      invalidFrame,
+    );
     assert.throws(
       () =>
         usageResponse({
@@ -778,6 +793,7 @@ function validSummary() {
     cacheHitRequests: 0,
     cacheCreateRequests: 0,
     errorRequests: 0,
+    totalDurationMs: 1_200,
   };
 }