@genesislcap/ai-assistant 15.12.0 → 15.13.0

package/src/main/main.ts

@@ -88,7 +88,7 @@ import {
   deleteDriver,
 } from '../state/driver-registry';
 import { buildTimelineEntries } from '../state/persistence/build-timeline-entries';
-import { assembleDebugLog } from '../state/persistence/diagnostics';
+import { assembleDebugLog, withFreshMetaSnapshot } from '../state/persistence/diagnostics';
 import type { DebugLog, DiagnosticEntry } from '../state/persistence/diagnostics';
 import {
   deleteDiagnosticsCursorsFor,
@@ -4044,7 +4044,7 @@ export class FoundationAiAssistant extends GenesisElement {
     );
   }
 
-  /** The live current-page debug log (`{ readme, timeline, meta }`). @public */
+  /** The live current-page debug log (`{ readme, sessionUsage, timeline, meta }`). @public */
   getDebugLog(): DebugLog {
     return assembleDebugLog(this.buildDiagnosticEntries(), DEBUG_LOG_README);
   }
@@ -4058,6 +4058,39 @@ export class FoundationAiAssistant extends GenesisElement {
    * been appended to the persisted stream.
    */
   private buildDiagnosticEntries(): DiagnosticEntry[] {
+    const stateKey = this.getStateKey();
+
+    // The message/turn/event timeline entries — built by the shared, pure `buildTimelineEntries`
+    // (the same helper a headless consumer uses to harvest its own log), from the driver's pull
+    // surfaces. Prefer the driver's raw history (carries sub-agent traces) over the redux projection.
+    const timelineEntries = buildTimelineEntries({
+      turnSnapshots: this.driver?.getTurnSnapshots?.() ?? [],
+      messages: this.driver?.getRawHistory?.() ?? this.messages,
+      metaEvents: stateKey ? getMetaEvents(stateKey) : [],
+    });
+
+    // Fold in any external diagnostics harvested from an out-of-band driver (e.g. a server-side
+    // ChatDriver whose collated log an interaction widget returned on its result). They ride the
+    // same download + persisted-diagnostics path; `assembleDebugLog` sorts the whole timeline by
+    // timestamp so they interleave chronologically. (GENC-1461 unified diagnostics.)
+    return [
+      ...timelineEntries,
+      ...(this.driver?.getExternalDiagnostics?.() ?? []),
+      this.buildMetaSnapshot(),
+    ] as DiagnosticEntry[];
+  }
+
+  /**
+   * The single `meta-snapshot` entry for right now — the export-time `meta` block
+   * (agent summary, active prompt/state, context + cost) plus the `dedupSignature`
+   * the forward-capture delta keys on.
+   *
+   * Separate from `buildDiagnosticEntries` because the download path needs a
+   * FRESH one on its own: the persisted stream only re-appends this block when the
+   * near-static config changes, so the newest stored snapshot's volatile half — the
+   * `context` figures especially — is typically frozen at the session's first flush.
+   */
+  private buildMetaSnapshot(): DiagnosticEntry {
     const timestamp = new Date().toISOString().replace(/:/g, '-');
     // Snapshot the live active agent from the DRIVER — the instance whose
     // `onActivate` ran, so its `getDebugSnapshot` closure holds state.
@@ -4074,16 +4107,6 @@ export class FoundationAiAssistant extends GenesisElement {
       this.contextTokens != null && this.contextLimit != null && this.contextLimit > 0
         ? Math.round((this.contextTokens / this.contextLimit) * 100)
         : undefined;
-    const stateKey = this.getStateKey();
-
-    // The message/turn/event timeline entries — built by the shared, pure `buildTimelineEntries`
-    // (the same helper a headless consumer uses to harvest its own log), from the driver's pull
-    // surfaces. Prefer the driver's raw history (carries sub-agent traces) over the redux projection.
-    const timelineEntries = buildTimelineEntries({
-      turnSnapshots: this.driver?.getTurnSnapshots?.() ?? [],
-      messages: this.driver?.getRawHistory?.() ?? this.messages,
-      metaEvents: stateKey ? getMetaEvents(stateKey) : [],
-    });
 
     // The export-time `meta` block, carried on a `meta-snapshot` entry so it lives
     // in the same forward stream (the latest one wins on reassembly, and the
@@ -4149,6 +4172,8 @@ export class FoundationAiAssistant extends GenesisElement {
     // instead of "only when the block actually changed". The volatile evolution is
     // already in the timeline (turn snapshots + `context.updated` events), so the
     // persister only needs a fresh meta-snapshot when the config/prompt changes.
+    // Consequence for the download path: the newest STORED snapshot's context/cost
+    // figures are stale, which is why `buildDownloadLog` appends a fresh one.
     const m = metaSnapshot.meta as Record<string, unknown>;
     metaSnapshot.dedupSignature = JSON.stringify({
       host: m.host,
@@ -4157,16 +4182,7 @@ export class FoundationAiAssistant extends GenesisElement {
       activePrimerHistory: m.activePrimerHistory,
       activeFoldStack: m.activeFoldStack,
     });
-
-    // Fold in any external diagnostics harvested from an out-of-band driver (e.g. a server-side
-    // ChatDriver whose collated log an interaction widget returned on its result). They ride the
-    // same download + persisted-diagnostics path; `assembleDebugLog` sorts the whole timeline by
-    // timestamp so they interleave chronologically. (GENC-1461 unified diagnostics.)
-    return [
-      ...timelineEntries,
-      ...(this.driver?.getExternalDiagnostics?.() ?? []),
-      metaSnapshot,
-    ] as DiagnosticEntry[];
+    return metaSnapshot;
   }
 
   async downloadDebugLog(): Promise<void> {
@@ -4200,6 +4216,14 @@ export class FoundationAiAssistant extends GenesisElement {
    * chat" — diagnostics are a forensic stream keyed on provider capability, not on
    * whether the *chat* is remembered (like preferences). Falls back to the live
    * current-page log when diagnostics isn't available or the fetch fails.
+   *
+   * The stored `meta-snapshot`s are replaced by a fresh one (`withFreshMetaSnapshot`)
+   * before reassembly. The persisted stream only re-appends that block when the
+   * near-static config signature changes (see `collectDiagnosticsDelta`), so on a session
+   * whose config never changes the newest STORED snapshot is the first one — its
+   * `context` half (session cost/usage, context tokens, live agent state) frozen seconds
+   * into the session, which is how a lifetime log came out reporting near-zero spend
+   * against a transcript full of priced messages.
    */
   private async buildDownloadLog(): Promise<DebugLog> {
     const provider = this.persistence.provider;
@@ -4209,7 +4233,12 @@ export class FoundationAiAssistant extends GenesisElement {
         // Land the current page's unflushed delta first so the download includes it.
         await this.persister()?.flushDiagnostics();
         const stored = await provider.loadDiagnostics(key);
-        if (stored.length) return assembleDebugLog(stored, DEBUG_LOG_README);
+        if (stored.length) {
+          return assembleDebugLog(
+            withFreshMetaSnapshot(stored, this.buildMetaSnapshot()),
+            DEBUG_LOG_README,
+          );
+        }
       } catch (e) {
         logger.error('Diagnostics load failed — using current-page log:', e);
       }

package/src/state/debug-event-log.ts

@@ -316,17 +316,22 @@ export function clearSession(key: string): void {
  */
 export const DEBUG_LOG_README: readonly string[] = [
   'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
+  "`sessionUsage` is what this session spent: `costUsd` (USD, provider-reported per request and summed, cache discounts already applied) plus the four TOKEN BUCKETS — `uncachedInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`. Those four are disjoint and safe to add up for a total-tokens figure; the per-message fields further down are NOT (see kind:'message'). Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a big token count against a small cost means the prompt was mostly cache hits, not a missing charge. It covers sub-agent turns and spend a compaction banked, so for the CONVERSATION it is the authoritative total: prefer it over re-summing the timeline, which can be short by whatever the ring buffers evicted. The same figures appear under `meta.context`. It is as current as the snapshot it came from: the assistant's own download stamps a fresh one, but a log stitched by another tool can carry an older one — compare `meta.timestamp` with the last timeline entry, and if it is well behind, read these totals as historical and fall back to summing the timeline. One scope caveat: it is derived from the transcript, so it excludes billed calls that produced no message (a blank or refused attempt that was retried — see kind:'turn'.`usage`). Summing the turns can therefore come out HIGHER than this, and the difference is exactly that discarded spend, not a double-count.",
+  "What 'session' means for those figures: the CURRENT conversation under this session key (a host-supplied per-project id, or the element id + header title when the host supplies none) — which is not necessarily everything in `timeline`. It is re-derived from the live transcript, so it spans page loads only when the chat is being remembered, and a Clear resets it to zero. `timeline` is append-only regardless: it keeps every page load and the pre-Clear conversation, with the session.cleared event as the boundary. So on a long-lived log, read these totals as the latest conversation's and the earlier sections as history — not as a total of the whole file.",
   '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
   'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',
   "kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result.",
   "Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\"<parent> › <sub-agent>\"` breadcrumb (composing when nested, e.g. `\"UI Builder › Planner › Grounding\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.",
   "kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
+  "kind:'turn'.`model`/`providerName`/`provider` — which model ran that call: the concrete model id, the registry slot it resolved under (a tier name like 'high'/'low', or the default), and the vendor. Recorded per CALL, so an agent whose `provider` selector varies by state — a flow that plans on a high tier and executes on a low one — has every step attributed, including calls that produced no message. `model` is the SERVING model where the provider reports one, so a turn answered by a server-side fallback names the model that answered rather than the one requested; it always matches the `model` on the message that call produced. Absent when the provider exposes no `getStatus` and the transport stamped nothing.",
+  "kind:'turn'.`usage` — what that ONE call cost, in the same four-bucket + `costUsd` shape as `sessionUsage`. Absent while a call is in flight and on providers that report no usage. This is the SAME money as the message the call produced, not extra money: never add turn usage to message usage, and read a turn plus its message as one charge. Its distinct value is the calls that produced NO message — a blank or refused response is billed and then discarded before the retry, so the turn entry is the only record of that spend, and a turn with `usage` but no message after it is exactly that. `costUsd: 0` alongside a nonzero token count means the provider reported no price, not that the call was free.",
   "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
   "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
   "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
-  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted; budget_exhausted is terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted; budget_exhausted is terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
   'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
-  "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
+  "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
+  'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',
   'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',
 ];
 

package/src/state/persistence/diagnostics.test.ts

@@ -1,5 +1,10 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { assembleDebugLog, diagnosticsMessageKey, type DiagnosticEntry } from './diagnostics';
+import {
+  assembleDebugLog,
+  diagnosticsMessageKey,
+  type DiagnosticEntry,
+  withFreshMetaSnapshot,
+} from './diagnostics';
 
 // GENC-1351 §5.8: `assembleDebugLog` reassembles the forward-only diagnostics
 // stream back into the `{ readme, timeline, meta }` debug-log shape — timeline
@@ -92,8 +97,210 @@ Suite('collapses exact-duplicate entries but keeps genuinely-distinct ones', ()
   );
 });
 
+Suite('lifts the newest snapshot’s session usage to the top of the log', () => {
+  // The four buckets + USD are the headline of a cost investigation, and `meta` is a
+  // large block to go digging in — so they surface at the top level. Same object, not a
+  // second derivation, and taken from the SAME snapshot that becomes `meta`.
+  const usage = {
+    costUsd: 1.25,
+    uncachedInputTokens: 1000,
+    cacheReadTokens: 9000,
+    cacheWriteTokens: 500,
+    outputTokens: 300,
+  };
+  const entries: DiagnosticEntry[] = [
+    {
+      kind: 'meta-snapshot',
+      timestamp: '2026-01-01T00:00:01.000Z',
+      meta: { context: { sessionUsage: { ...usage, costUsd: 0.01 } } },
+    },
+    {
+      kind: 'meta-snapshot',
+      timestamp: '2026-01-01T00:00:09.000Z',
+      meta: { context: { sessionUsage: usage } },
+    },
+  ];
+  assert.equal(assembleDebugLog(entries, README).sessionUsage, usage);
+});
+
+Suite('leaves session usage undefined when no snapshot carries it', () => {
+  // A stream with no meta-snapshot, or one written before the field existed. Absent
+  // rather than zeroed: "not recorded" must not read as "this session spent nothing".
+  assert.is(assembleDebugLog([], README).sessionUsage, undefined);
+  const noContext: DiagnosticEntry[] = [
+    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:00:01.000Z', meta: { host: 'localhost' } },
+  ];
+  assert.is(assembleDebugLog(noContext, README).sessionUsage, undefined);
+});
+
+Suite('collapses the turn pair even when its rendered systemPrompt differs', () => {
+  // The pair is produced by two separate flushes, and `buildTimelineEntries` renders
+  // `systemPrompt` relative to the preceding snapshots — so if the snapshot holding the
+  // full prompt is evicted from the ring buffer between the two, the surviving turn
+  // renders its prompt in full where the earlier copy had the '<repeated>' marker. Any
+  // identity derived from the serialized entry breaks here and the log shows one model
+  // call as two turns, one unpriced. Identity is turnIndex + timestamp + agentName.
+  const unpriced: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '7',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    agentName: 'Trade Operations',
+    systemPrompt: '<repeated — identical to turn 0>',
+    toolNames: [],
+  };
+  const priced: DiagnosticEntry = {
+    ...unpriced,
+    systemPrompt: 'the full prompt, now that turn 0 has been evicted',
+    usage: {
+      costUsd: 0.5,
+      uncachedInputTokens: 100,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      outputTokens: 20,
+    },
+  };
+  const turns = assembleDebugLog([unpriced, priced], README).timeline.filter(
+    (e) => e.kind === 'turn',
+  );
+  assert.is(turns.length, 1, 'still one model call');
+  assert.equal(turns[0].usage, priced.usage, 'and it is the priced copy');
+});
+
+Suite('keeps same-index turns from different loads and different sub-agents apart', () => {
+  // `turnIndex` restarts at '0' on every page load, so a lifetime log holds one turn '0'
+  // per load; two sub-agents invoked in one parent turn share the index prefix and are
+  // separated by `agentName` (see `forwardSubAgentSnapshots`).
+  const load1: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    agentName: 'Booker',
+    toolNames: [],
+  };
+  const load2: DiagnosticEntry = { ...load1, timestamp: '2026-01-02T09:00:00.000Z' };
+  const sibling: DiagnosticEntry = { ...load1, turnIndex: '3-1', agentName: 'Planner' };
+  const cousin: DiagnosticEntry = { ...sibling, agentName: 'Grounding' };
+  const turns = assembleDebugLog([load1, load2, sibling, cousin], README).timeline.filter(
+    (e) => e.kind === 'turn',
+  );
+  assert.is(turns.length, 4, 'four distinct calls, none collapsed');
+});
+
+Suite('collapses the unpriced and priced copies of one turn onto the priced one', () => {
+  // A turn entry is persisted when it is created (before its model call) and again once
+  // `usage` is back-filled, so a stitched stream carries both. They are ONE model call
+  // and must read as one — with the cost, or the re-emit gained nothing.
+  const unpriced: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    toolNames: [],
+  };
+  const priced: DiagnosticEntry = {
+    ...unpriced,
+    usage: {
+      costUsd: 0.5,
+      uncachedInputTokens: 100,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      outputTokens: 20,
+    },
+  };
+  for (const order of [
+    [unpriced, priced],
+    [priced, unpriced],
+  ]) {
+    const turns = assembleDebugLog(order, README).timeline.filter((e) => e.kind === 'turn');
+    assert.is(turns.length, 1, 'one turn, not two');
+    assert.equal(turns[0].usage, priced.usage, 'the priced copy wins regardless of stream order');
+  }
+});
+
+Suite('keeps two genuinely-different turns that differ only in usage', () => {
+  // The collapse keys on everything EXCEPT usage, so distinct calls stay distinct — they
+  // differ in timestamp (and turnIndex) whatever else they share.
+  const a: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    toolNames: [],
+  };
+  const b: DiagnosticEntry = { ...a, turnIndex: '1', timestamp: '2026-01-01T00:00:02.000Z' };
+  const turns = assembleDebugLog([a, b], README).timeline.filter((e) => e.kind === 'turn');
+  assert.is(turns.length, 2);
+});
+
 Suite.run();
 
+// The download path's swap: a stored stream's `meta-snapshot`s replaced by an export-time
+// one. This is the fix for a SILENT bug — the persisted stream only re-appends that block
+// when the config signature changes, so a stitched lifetime log reported the totals frozen
+// at the session's first flush (near-zero spend against a transcript full of priced
+// messages) and nothing about it looked wrong.
+const FreshSuite = createLogicSuite('withFreshMetaSnapshot');
+
+const storedStream: DiagnosticEntry[] = [
+  {
+    kind: 'meta-snapshot',
+    timestamp: '2026-01-01T00:00:00.000Z',
+    meta: { context: { sessionUsage: { costUsd: 0.01 } } },
+    dedupSignature: 'cfg-1',
+  },
+  { kind: 'message', timestamp: '2026-01-01T00:00:01.000Z', role: 'user', content: 'hi' },
+  { kind: 'turn', turnIndex: '0', timestamp: '2026-01-01T00:00:02.000Z', toolNames: [] },
+  { kind: 'event', index: 0, timestamp: '2026-01-01T00:00:03.000Z', type: 'turn.end' },
+];
+
+const freshSnapshot: DiagnosticEntry = {
+  kind: 'meta-snapshot',
+  timestamp: '2026-01-01T02:00:00.000Z',
+  meta: {
+    context: {
+      sessionUsage: {
+        costUsd: 1.25,
+        uncachedInputTokens: 1000,
+        cacheReadTokens: 9000,
+        cacheWriteTokens: 500,
+        outputTokens: 300,
+      },
+    },
+  },
+  dedupSignature: 'cfg-1',
+};
+
+FreshSuite('reports the export-time totals, not the frozen stored ones', () => {
+  const log = assembleDebugLog(withFreshMetaSnapshot(storedStream, freshSnapshot), README);
+  assert.is(log.sessionUsage?.costUsd, 1.25, 'the fresh snapshot supplies the totals');
+  assert.is(log.sessionUsage?.cacheReadTokens, 9000);
+  assert.equal(log.meta, freshSnapshot.meta, 'and the whole meta block is the fresh one');
+});
+
+FreshSuite('keeps every non-snapshot entry', () => {
+  const timeline = assembleDebugLog(
+    withFreshMetaSnapshot(storedStream, freshSnapshot),
+    README,
+  ).timeline;
+  assert.equal(
+    timeline.map((e) => e.kind),
+    ['message', 'turn', 'event'],
+    'the conversation is untouched — only the snapshots are swapped',
+  );
+});
+
+FreshSuite('wins even when the stored snapshot claims a later time', () => {
+  // A stream written on another machine can carry a skewed clock, and reassembly keeps
+  // whichever snapshot claims the later timestamp — so the stale one must be REMOVED
+  // rather than out-timestamped.
+  const skewed: DiagnosticEntry[] = [
+    { ...storedStream[0], timestamp: '2099-01-01T00:00:00.000Z' },
+    ...storedStream.slice(1),
+  ];
+  const log = assembleDebugLog(withFreshMetaSnapshot(skewed, freshSnapshot), README);
+  assert.is(log.sessionUsage?.costUsd, 1.25);
+});
+
+FreshSuite.run();
+
 // GENC-1461: the reasoning/narration/answer split (GENC-1411) emits several messages from ONE model
 // response, so they share `timestamp` + `role` + `subAgentOf`. The message identity key must still
 // tell them apart — otherwise the forward-capture dedup treats them as one and drops all but the

package/src/state/persistence/diagnostics.ts

@@ -2,19 +2,21 @@
  * Server-saved diagnostics (GENC-1351 §5.8) — the forward-only stream that lets
  * the debug log persist across a whole session lifetime, not just the current
  * page load. This module owns the *pure* pieces: the entry type and the
- * reassembly back into the `{ readme, timeline, meta }` debug-log shape. The
- * element owns capture/cadence; the provider owns storage layout.
+ * reassembly back into the `{ readme, sessionUsage, timeline, meta }` debug-log
+ * shape. The element owns capture/cadence; the provider owns storage layout.
  *
  * @packageDocumentation
  */
 
+import type { AggregateUsage } from '@genesislcap/foundation-ai';
+
 /**
  * One entry in the diagnostics stream — the debug-log timeline-entry union
  * (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time
  * **`meta-snapshot`** carrying the export-time `meta` block (agent summary,
  * context, active debug snapshot, …). Kept permissive: a provider stores and
  * returns these opaquely, and reassembly reads only `kind`, `timestamp` (for
- * ordering), and `meta` (on a snapshot).
+ * ordering), `usage` (on a turn) and `meta` (on a snapshot).
  *
  * @public
  */
@@ -24,6 +26,16 @@ export interface DiagnosticEntry {
   timestamp?: string;
   /** Present on `meta-snapshot` entries: the export-time `meta` block. */
   meta?: unknown;
+  /**
+   * Present on a `turn` entry once its model call has returned and reported usage —
+   * the four token buckets plus USD for that one call (`TurnSnapshot.usage`).
+   *
+   * Read by the forward-capture delta as well as by readers: the turn entry is
+   * created *before* the call, so a flush that lands mid-call persists it without
+   * usage, and the delta re-emits it once (see `collectDiagnosticsDelta`) so the
+   * priced copy reaches the stream. {@link assembleDebugLog} then collapses the pair.
+   */
+  usage?: AggregateUsage;
   /**
    * Present on `meta-snapshot` entries: a stable signature of the near-static config
    * (excludes volatile timestamp/context/debug-snapshot), used by the forward-capture
@@ -37,6 +49,27 @@ export interface DiagnosticEntry {
 /** The reassembled debug log — the exact shape `getDebugLog()` returns. @public */
 export interface DebugLog {
   readme: readonly string[];
+  /**
+   * Session usage — the four token buckets plus USD cost — lifted out of the newest
+   * `meta-snapshot`'s `meta.context.sessionUsage` so the headline spend figures sit at
+   * the top of an exported log rather than buried under the (large) `meta` block. The
+   * same object, not a second derivation.
+   *
+   * `undefined` when the stream carries no `meta-snapshot`, or one written before the
+   * field existed. Never re-derived from the timeline: the per-request costs the
+   * transports stamped are authoritative, and a ring-buffered timeline can have lost
+   * entries the total still legitimately counts.
+   *
+   * **As current as the snapshot it came from, which is not automatically "now".** The
+   * forward-capture delta only re-appends a `meta-snapshot` when the near-static config
+   * signature changes, so the newest STORED snapshot of a session whose config never
+   * changed is its first — with the totals frozen there. A caller reassembling a stored
+   * stream on its own therefore gets stale figures unless it appends an export-time
+   * snapshot first: see {@link withFreshMetaSnapshot}, which is what the assistant's own
+   * download path does. `meta.timestamp` against the newest timeline entry tells you
+   * which case you are holding.
+   */
+  sessionUsage?: AggregateUsage;
   timeline: DiagnosticEntry[];
   meta: unknown;
 }
@@ -65,6 +98,28 @@ export function diagnosticsMessageKey(entry: DiagnosticEntry): string | null {
     : null;
 }
 
+/**
+ * Identity of a `turn` entry — `turnIndex::timestamp::agentName`.
+ *
+ * Deliberately NOT the serialized entry, which two copies of the same call do not always
+ * share. `buildTimelineEntries` renders `systemPrompt` *relative to the preceding
+ * snapshots* (collapsing it to `<repeated — identical to turn N>` when it matches the
+ * previous full prompt), so if the snapshot holding that full prompt is evicted from the
+ * ring buffer between the unpriced flush and the priced one, the surviving turn renders
+ * its prompt differently and the two serializations diverge. Both copies are in the
+ * stream by then, so nothing would collapse them — and the log whose purpose is per-call
+ * cost would show one model call as two turns, one of them unpriced.
+ *
+ * All three components are fixed when the snapshot is created and never re-derived.
+ * `turnIndex` alone is not enough: it restarts at `'0'` on each page load, and a lifetime
+ * log legitimately holds one turn `'0'` per load. `agentName` separates two sub-agents
+ * invoked in the same parent turn, which share a `turnIndex` prefix by construction (see
+ * `forwardSubAgentSnapshots`).
+ */
+function turnIdentity(entry: DiagnosticEntry): string {
+  return `turn::${String(entry.turnIndex ?? '')}::${entry.timestamp ?? ''}::${String(entry.agentName ?? '')}`;
+}
+
 // Tie-break co-timestamped entries by cause → call → output (event, turn, message),
 // matching the original in-place `getDebugLog` sort.
 const KIND_RANK: Record<string, number> = { event: 0, turn: 1, message: 2 };
@@ -73,16 +128,23 @@ const KIND_RANK: Record<string, number> = { event: 0, turn: 1, message: 2 };
 const UNKNOWN_KIND_RANK = 99;
 
 /**
- * Reassemble diagnostic entries into the `{ readme, timeline, meta }` debug-log
- * shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
+ * Reassemble diagnostic entries into the `{ readme, sessionUsage, timeline, meta }`
+ * debug-log shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
  * by ISO `timestamp` (kind-rank tie-break). `meta` = the **newest** `meta-snapshot`'s
  * block only — a "state at export" photo, matching the single-page log. The older
  * snapshots are intentionally dropped: the per-turn evolution they would show is
  * already in the timeline (`turn.agentSnapshot` + `context.updated` events), so
  * keeping them would just repeat the bulky, near-static `agentSummary`. `readme` =
- * the passed (current) constant. Pure — reused for both the live current-page log
- * and the reassembled lifetime log stitched from the persisted stream, so both
- * come out shape-identical.
+ * the passed (current) constant. `sessionUsage` = that same newest snapshot's
+ * `meta.context.sessionUsage`, lifted to the top level. Pure — reused for both the
+ * live current-page log and the reassembled lifetime log stitched from the persisted
+ * stream, so both come out shape-identical.
+ *
+ * NOTE for a caller stitching a STORED stream (a headless consumer harvesting its own
+ * lifetime log, say): the newest stored `meta-snapshot` is frozen at the last
+ * config-signature change, so `meta` and `sessionUsage` are as old as that unless you
+ * pass a fresh snapshot of your own — {@link withFreshMetaSnapshot} does exactly that,
+ * and the element's download path goes through it.
  */
 export function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly string[]): DebugLog {
   // Safety net for exact-duplicate entries: two element instances sharing one
@@ -92,20 +154,31 @@ export function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly st
   // (e.g. two real `assistant.connected` from two instances) differ in index /
   // placement and are kept. (The shared cursor store prevents most of this at
   // write time; this guards the read path regardless of what's in the stream.)
-  const seen = new Set<string>();
+  //
+  // A `turn` is identified by `turnIndex` + `timestamp` + `agentName` instead (see
+  // `turnIdentity`), so the unpriced copy a mid-call flush persisted and the priced copy
+  // that follows it collapse into ONE turn — the priced one — rather than reading as two
+  // model calls.
+  const seenAt = new Map<string, number>();
   let latestMeta: DiagnosticEntry | undefined;
   const timeline: DiagnosticEntry[] = [];
   for (const entry of entries) {
-    const id = JSON.stringify(entry);
-    if (seen.has(id)) continue;
-    seen.add(id);
     if (entry.kind === 'meta-snapshot') {
       if (!latestMeta || (entry.timestamp ?? '') >= (latestMeta.timestamp ?? '')) {
         latestMeta = entry;
       }
-    } else {
-      timeline.push(entry);
+      continue;
+    }
+    const id = entry.kind === 'turn' ? turnIdentity(entry) : JSON.stringify(entry);
+    const at = seenAt.get(id);
+    if (at !== undefined) {
+      // Same entry seen twice — keep the richer copy. `usage` on a turn is the only
+      // field that can arrive late, so it is the only upgrade there is to make.
+      if (entry.usage && !timeline[at].usage) timeline[at] = entry;
+      continue;
     }
+    seenAt.set(id, timeline.length);
+    timeline.push(entry);
   }
   timeline.sort((a, b) => {
     const ta = a.timestamp ?? '';
@@ -114,5 +187,34 @@ export function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly st
     if (ta > tb) return 1;
     return (KIND_RANK[a.kind] ?? UNKNOWN_KIND_RANK) - (KIND_RANK[b.kind] ?? UNKNOWN_KIND_RANK);
   });
-  return { readme, timeline, meta: latestMeta?.meta };
+  // The session totals live inside the newest snapshot's `meta`, which is `unknown` by
+  // design (a provider stores these opaquely) — so this narrows just the one path it
+  // reads rather than typing the whole block.
+  const context = (latestMeta?.meta as { context?: { sessionUsage?: AggregateUsage } } | undefined)
+    ?.context;
+  return { readme, sessionUsage: context?.sessionUsage, timeline, meta: latestMeta?.meta };
+}
+
+/**
+ * A stored diagnostics stream with its `meta-snapshot`s replaced by `fresh` — what to
+ * pass {@link assembleDebugLog} when reassembling a persisted stream for export.
+ *
+ * The stored snapshots are dropped rather than out-timestamped. `assembleDebugLog` keeps
+ * whichever claims the later time, and a stream written on another machine can carry a
+ * skewed clock; `fresh` is built from live state and so is the more current by
+ * construction. Only one snapshot ever survives reassembly, so the count is unchanged —
+ * though a snapshot taken while the driver is unwired (mid-popout) can leave
+ * `activeFoldStack`/`activeDebugSnapshot` unset where a stored one had them. The figures
+ * this exists for — the context block and `sessionUsage` — read the session store and
+ * element props, which survive an unwire.
+ *
+ * Pure, and separate from the element for that reason: the swap it performs is the fix
+ * for a silent bug (a lifetime log reporting near-zero spend against a transcript full of
+ * priced messages), so it needs to be testable without mounting anything.
+ */
+export function withFreshMetaSnapshot(
+  stored: readonly DiagnosticEntry[],
+  fresh: DiagnosticEntry,
+): DiagnosticEntry[] {
+  return [...stored.filter((e) => e.kind !== 'meta-snapshot'), fresh];
 }

package/src/state/persistence/index.ts

@@ -6,5 +6,5 @@ export type {
   SessionPersistenceConfig,
   SessionPreferences,
 } from './session-persistence-provider';
-export { assembleDebugLog } from './diagnostics';
+export { assembleDebugLog, withFreshMetaSnapshot } from './diagnostics';
 export type { DiagnosticEntry, DebugLog } from './diagnostics';