@genesislcap/ai-assistant 15.4.1 → 15.5.0

package/src/provider/assistant-app-settings.ts

@@ -21,16 +21,42 @@ export interface AssistantAppSettingsToggle {
 }
 
 /**
- * App-supplied settings for the platform settings modal UI Builder section.
- * Register a concrete implementation on the DI token at app bootstrap; the
- * assistant renders toggles with the same row layout as AI Chat Bot settings.
+ * Optional heading above a provider's toggle group.
+ *
+ * Entirely host-supplied — the assistant has no default title and no default icon, because the
+ * section belongs to the host. Omit it and the toggles render bare, which is right when the
+ * host's slotted content already titles them.
+ *
+ * @beta
+ */
+export interface AssistantAppSettingsHeading {
+  readonly title: string;
+  /**
+   * Icon name for the design system's icon element (a Font Awesome free name, e.g.
+   * `'object-group'`). Omitted renders text only; an unknown name renders nothing at all, so
+   * check it against the installed Font Awesome set.
+   */
+  readonly icon?: string;
+}
+
+/**
+ * App-supplied settings for the host's own section of the settings modal. Register a concrete
+ * implementation on the DI token at app bootstrap; the assistant renders the toggles with the
+ * same row layout as AI Chat Bot settings.
+ *
+ * The section itself is untitled by the assistant — no heading text and no icon — because only
+ * the host knows what it is. Title it from the `settings-app` slot, which renders above these
+ * toggles, and apply `assistantSettingsSectionTitleStyles` to match the built-in headings.
  *
  * @beta
  */
 export interface AssistantAppSettingsProvider {
-  /** Section heading. Default: `"UI Builder Settings"`. */
-  readonly sectionTitle?: string;
   readonly toggles: readonly AssistantAppSettingsToggle[];
+  /**
+   * Heading for the toggle group, for hosts that put other controls in the `settings-app` slot
+   * and need these distinguished from them. No default: absent means no heading.
+   */
+  readonly togglesHeading?: AssistantAppSettingsHeading;
   getValue(id: string): boolean;
   setValue(id: string, value: boolean): void;
   /** Notify the assistant to re-read toggle values / visibility. */

package/src/state/ai-assistant-slice.test.ts

@@ -28,10 +28,14 @@ Suite('loadSession hydrates the restorable fields and forces idle', () => {
   let start = createDefaultSessionState();
   start = reduce(start, setState('loading')); // prove it overrides any prior state
   const payload: LoadSessionPayload = {
-    messages: [{ role: 'user', content: 'hi' }] as ChatMessage[],
+    // Usage rides on the message: `loadSession` derives the session totals from the
+    // restored transcript rather than from a stored counter, so the cost has to be in
+    // the messages for the assertion below to see it.
+    messages: [
+      { role: 'user', content: 'hi', cost: 1.25, inputTokens: 100, outputTokens: 20 },
+    ] as ChatMessage[],
     pinnedAgentName: 'Guided Booking',
     flowOwnerAgentName: 'Guided Booking',
-    sessionCostUsd: 1.25,
     contextTokens: 1200,
     contextLimit: 200000,
     activeModel: 'claude-sonnet-4-6',
@@ -41,7 +45,11 @@ Suite('loadSession hydrates the restorable fields and forces idle', () => {
   assert.is(next.messages.length, 1);
   assert.is(next.pinnedAgentName, 'Guided Booking');
   assert.is(next.flowOwnerAgentName, 'Guided Booking');
-  assert.is(next.sessionCostUsd, 1.25);
+  assert.is(next.sessionUsage.costUsd, 1.25);
+  // Derived from the same walk: 100 prompt tokens with no cache split reported, so all
+  // of it is uncached input, plus the 20 generated.
+  assert.is(next.sessionUsage.uncachedInputTokens, 100);
+  assert.is(next.sessionUsage.outputTokens, 20);
   assert.is(next.contextTokens, 1200);
   assert.is(next.contextLimit, 200000);
   assert.is(next.activeModel, 'claude-sonnet-4-6');
@@ -58,7 +66,6 @@ Suite('resetSession wipes back to a fresh default', () => {
       messages: [],
       pinnedAgentName: 'A',
       flowOwnerAgentName: 'A',
-      sessionCostUsd: 9,
       contextTokens: 5,
       contextLimit: 10,
       activeModel: 'm',
@@ -67,7 +74,7 @@ Suite('resetSession wipes back to a fresh default', () => {
   );
   const cleared = reduce(state, resetSession());
   assert.is(cleared.messages.length, 0);
-  assert.is(cleared.sessionCostUsd, 0);
+  assert.is(cleared.sessionUsage.costUsd, 0);
   assert.is(cleared.pinnedAgentName, null);
   assert.is(cleared.flowOwnerAgentName, null);
   assert.is(cleared.contextTokens, undefined);

package/src/state/ai-assistant-slice.ts

@@ -1,4 +1,5 @@
 import type {
+  AggregateUsage,
   AIProviderRegistryStatusEntry,
   ChatInputDuringExecutionMode,
   ChatMessage,
@@ -7,6 +8,7 @@ import type { PayloadAction } from '@genesislcap/foundation-redux';
 import { createSlice } from '@genesislcap/foundation-redux';
 import type { AgentConfig } from '../config/config';
 import type { AiAssistantAnimation, AiAssistantState, SuggestionsState } from '../main/main.types';
+import { emptyUsage, sumUsage } from '../utils/sum-usage';
 
 /**
  * A single in-flight per-call chat-input override pushed by a `requestSubAgent`
@@ -40,10 +42,15 @@ export interface AiAssistantSessionState {
   suggestionsState: SuggestionsState;
   contextTokens: number | undefined;
   contextLimit: number | undefined;
-  /** Aggregated USD cost across every chat turn in this session. */
-  sessionCostUsd: number;
-  /** Cumulative input + output tokens across every chat turn in this session. */
-  sessionTokensConsumed: number;
+  /**
+   * Cost and per-bucket token totals across every chat turn in this session,
+   * including sub-agent turns and spend banked by a compaction.
+   *
+   * One field rather than a cost scalar plus a token scalar: they are derived from
+   * the same walk of the transcript, so keeping them together makes it impossible
+   * for the two to disagree about which turns they counted.
+   */
+  sessionUsage: AggregateUsage;
   /** Active model id (e.g. `claude-sonnet-4-6`), resolved on connect. */
   activeModel: string | undefined;
   /**
@@ -137,7 +144,6 @@ export interface LoadSessionPayload {
   messages: ChatMessage[];
   pinnedAgentName: string | null;
   flowOwnerAgentName: string | null;
-  sessionCostUsd: number;
   contextTokens: number | undefined;
   contextLimit: number | undefined;
   activeModel: string | undefined;
@@ -161,8 +167,7 @@ export function createDefaultSessionState(): AiAssistantSessionState {
     suggestionsState: { status: 'idle' },
     contextTokens: undefined,
     contextLimit: undefined,
-    sessionCostUsd: 0,
-    sessionTokensConsumed: 0,
+    sessionUsage: emptyUsage(),
     activeModel: undefined,
     activeProviderName: undefined,
     providerStatuses: [],
@@ -217,11 +222,8 @@ export const aiAssistantSlice = createSlice({
     setContextLimit(state, action: PayloadAction<number | undefined>) {
       state.contextLimit = action.payload;
     },
-    setSessionCostUsd(state, action: PayloadAction<number>) {
-      state.sessionCostUsd = action.payload;
-    },
-    setSessionTokensConsumed(state, action: PayloadAction<number>) {
-      state.sessionTokensConsumed = action.payload;
+    setSessionUsage(state, action: PayloadAction<AggregateUsage>) {
+      state.sessionUsage = action.payload;
     },
     setActiveModel(state, action: PayloadAction<string | undefined>) {
       state.activeModel = action.payload;
@@ -282,7 +284,13 @@ export const aiAssistantSlice = createSlice({
       state.messages = p.messages;
       state.pinnedAgentName = p.pinnedAgentName;
       state.flowOwnerAgentName = p.flowOwnerAgentName;
-      state.sessionCostUsd = p.sessionCostUsd;
+      // Derive the totals from the restored transcript rather than trusting a stored
+      // counter. Restore dispatches this action directly, bypassing the host's
+      // `messages` setter — the thing that normally recomputes — so a stored total
+      // would sit stale (historically at 0) until the next turn arrived. The
+      // transcript is the source of truth: per-message usage survives the snapshot,
+      // and a compacted summary carries the usage of the turns it replaced.
+      state.sessionUsage = sumUsage(p.messages);
       state.contextTokens = p.contextTokens;
       state.contextLimit = p.contextLimit;
       state.activeModel = p.activeModel;

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

@@ -313,8 +313,8 @@ export const DEBUG_LOG_README: readonly string[] = [
   'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
   '`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, and `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`/`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:'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'.`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'.",

package/src/state/persistence/session-persistence-provider.ts

@@ -1,3 +1,4 @@
+import type { CostSessionRecord } from '../../utils/cost-session-history';
 import type { DiagnosticEntry } from './diagnostics';
 import type { PersistedSession } from './session-snapshot';
 
@@ -43,6 +44,29 @@ export interface SessionPersistenceProvider {
   /** Persist the user's UI preferences for `sessionKey` (kept across `clear`). */
   savePreferences?(sessionKey: string, preferences: SessionPreferences): Promise<void>;
 
+  /**
+   * Scoped cost/build history — the per-project usage rows behind the Usage tab.
+   *
+   * ‼️ **Keyed by SCOPE, not `sessionKey`**, unlike every other method on this interface.
+   * A row holds one project's lifetime usage and the list spans projects, so keying it
+   * per session would defeat the model. The scope comes from
+   * `chatConfig.costHistory.scope`, falling back to the element `id`, then `'default'`.
+   *
+   * Optional: when a provider omits these, the assistant falls back to `localStorage`, so
+   * hosts that don't implement them are unaffected. Implementing them moves the ledger to
+   * the host's own backend, which is what stops it being stranded in one browser.
+   *
+   * Read/written **independently of the `enabled` toggle** (as with preferences and
+   * diagnostics): usage accounting is not conversation content, so a user turning off
+   * chat retention should not lose their cost ledger. Best-effort — a failed write must
+   * never affect the chat.
+   *
+   * `undefined` from `loadCostHistory` means "nothing stored", the same as `[]`.
+   */
+  loadCostHistory?(scope: string): Promise<CostSessionRecord[] | undefined>;
+  /** Replace the stored row list for `scope`. See {@link SessionPersistenceProvider.loadCostHistory}. */
+  saveCostHistory?(scope: string, records: CostSessionRecord[]): Promise<void>;
+
   /**
    * Server-saved diagnostics (GENC-1351 §5.8) — a **forward-only append** stream
    * that lets the downloadable debug log span the whole session lifetime, not just

package/src/state/persistence/session-persistence.integration.test.ts

@@ -77,7 +77,14 @@ Suite('save → reload → restore brings back messages, selection, counters', a
   const restored = reduce(freshStore, loadSession(toLoadSessionPayload(snapshot!)));
   assert.is(restored.messages.length, 2);
   assert.is(restored.pinnedAgentName, 'Guided Booking');
-  assert.is(restored.sessionCostUsd, 0.5);
+  // Cost comes from the restored transcript, NOT the snapshot's stored counter — so it
+  // is whatever the messages actually carry. Computed independently here rather than
+  // by calling the summing helper under test.
+  const expectedCost = restored.messages.reduce(
+    (sum, m) => sum + (m.cost ?? 0) + (m.externalCostUsd ?? 0),
+    0,
+  );
+  assert.is(restored.sessionUsage.costUsd, expectedCost);
   assert.is(restored.contextTokens, 800);
   assert.is(restored.contextLimit, 200000);
   assert.is(restored.activeModel, 'claude-sonnet-4-6');

package/src/state/persistence/session-persister.test.ts

@@ -101,7 +101,16 @@ function makePersister(over: Partial<Fakes> = {}): { p: SessionPersister; f: Fak
         flowActivationPrompt: null,
         activeAgent: undefined,
         pinnedAgentName: null,
-        sessionCostUsd: 0,
+        // Inline rather than via `emptyUsage()` to keep this mock self-contained. The
+        // shape matters: the persister reads `sessionUsage.costUsd`, so a mock missing
+        // the object crashes the autosave timer rather than failing an assertion.
+        sessionUsage: {
+          costUsd: 0,
+          uncachedInputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+          outputTokens: 0,
+        },
         get restoring() {
           return f.restoring;
         },

package/src/state/persistence/session-persister.ts

@@ -282,7 +282,7 @@ export class SessionPersister {
           activeAgentName: s.activeAgent?.name,
           pinnedAgentName: s.pinnedAgentName,
           flowOwnerAgentName: null,
-          sessionCostUsd: s.sessionCostUsd,
+          sessionCostUsd: s.sessionUsage.costUsd,
           contextTokens: s.contextTokens,
           contextLimit: s.contextLimit,
           activeModel: s.activeModel,
@@ -316,7 +316,7 @@ export class SessionPersister {
       activeAgentName: s.activeAgent?.name,
       pinnedAgentName: s.pinnedAgentName,
       flowOwnerAgentName: s.flowOwnerAgentName,
-      sessionCostUsd: s.sessionCostUsd,
+      sessionCostUsd: s.sessionUsage.costUsd,
       contextTokens: s.contextTokens,
       contextLimit: s.contextLimit,
       activeModel: s.activeModel,

package/src/state/persistence/session-snapshot.test.ts

@@ -74,7 +74,10 @@ Suite('toLoadSessionPayload projects only the redux-restorable fields', () => {
   const p = toLoadSessionPayload(base());
   assert.is(p.pinnedAgentName, 'A');
   assert.is(p.flowOwnerAgentName, null);
-  assert.is(p.sessionCostUsd, 2);
+  // Cost is deliberately NOT projected — the slice re-derives it (and the token
+  // buckets) from `messages`, so a stored counter would be a second, divergeable
+  // source of truth.
+  assert.is((p as { sessionCostUsd?: number }).sessionCostUsd, undefined);
   assert.is(p.contextTokens, 10);
   assert.is(p.contextLimit, 100);
   assert.is(p.activeModel, 'm');

package/src/state/persistence/session-snapshot.ts

@@ -190,7 +190,11 @@ export function toLoadSessionPayload(s: PersistedSession): LoadSessionPayload {
     messages: s.messages,
     pinnedAgentName: s.pinnedAgentName ?? null,
     flowOwnerAgentName: s.flowOwnerAgentName ?? null,
-    sessionCostUsd: s.sessionCostUsd ?? 0,
+    // `sessionCostUsd` is deliberately NOT projected: the slice re-derives cost and
+    // token totals from `messages` on load. The snapshot field is still written (its
+    // shape is public, and it is a useful cross-check in a saved blob), but it is no
+    // longer authoritative — a snapshot saved mid-reset could hold a zeroed total
+    // while its transcript still shows the spend.
     contextTokens: s.contextTokens,
     contextLimit: s.contextLimit,
     activeModel: s.activeModel,

package/src/state/persistence/stateful-restore.e2e.test.ts

@@ -81,7 +81,15 @@ function makeStoreFake(over: Record<string, unknown> = {}) {
         flowActivationPrompt: null as string | null,
         activeAgent: undefined as { name: string } | undefined,
         pinnedAgentName: null as string | null,
-        sessionCostUsd: 0,
+        // The persister reads `sessionUsage.costUsd` when building a snapshot, so this
+        // has to be the object rather than a bare cost scalar.
+        sessionUsage: {
+          costUsd: 0,
+          uncachedInputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+          outputTokens: 0,
+        },
         contextTokens: 0,
         contextLimit: 0,
         activeModel: undefined,

package/src/styles/settings-section.ts

@@ -0,0 +1,40 @@
+import { css, type ElementStyles } from '@genesislcap/web-core';
+
+/**
+ * Heading style for a settings-modal section, published so a host can title its own section.
+ *
+ * The assistant renders no heading for the `settings-app` slot — no text and no icon — because
+ * only the host knows what that section is. The consequence is that a host supplying one has to
+ * reproduce the styling of the built-in headings beside it, and a copied rule drifts the moment
+ * either side changes. So the declarations live here, are applied by the assistant's own
+ * headings, and are exported for the host to apply to its.
+ *
+ * Compose it into a component's styles and put `ai-settings-section-title` on the heading:
+ *
+ * ```ts
+ * import { assistantSettingsSectionTitleStyles } from '@genesislcap/ai-assistant';
+ *
+ * const styles = css`
+ *   ${assistantSettingsSectionTitleStyles}
+ *   :host { display: block; }
+ * `;
+ * ```
+ *
+ * Carries no margin on purpose: spacing belongs to the surrounding layout, which differs
+ * between the assistant's own sections and a slotted one, and is the single declaration hosts
+ * had to diverge on when they copied this rule.
+ *
+ * @beta
+ */
+export const assistantSettingsSectionTitleStyles: ElementStyles = css`
+  .ai-settings-section-title {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--design-unit) * 2px);
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--neutral-foreground-hint);
+  }
+`;

package/src/utils/cost-session-history.test.ts

@@ -1,23 +1,36 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import type { CostSessionRecord } from './cost-session-history';
 import {
-  appendCostSessionRecord,
   clearCostSessionHistory,
   costHistoryStorageKey,
   formatCostSessionDate,
   loadCostSessionHistory,
-  removeCostSessionRecord,
+  resolveBankedUsage,
   saveCostSessionHistory,
+  sortRecordsByRecency,
+  upsertRecord,
 } from './cost-session-history';
+import { emptyUsage } from './sum-usage';
 
 const scope = `test-${Date.now()}`;
 
+const usage = (costUsd: number): CostSessionRecord['usage'] => ({
+  costUsd,
+  uncachedInputTokens: 100_000,
+  cacheReadTokens: 1_200_000,
+  cacheWriteTokens: 60_000,
+  outputTokens: 40_000,
+});
+
 const sampleRecord = (overrides: Partial<CostSessionRecord> = {}): CostSessionRecord => ({
   id: 'rec-1',
+  projectKey: 'proj-1',
   title: 'Equity Options Pricer',
-  endedAt: '2026-06-14T12:00:00.000Z',
-  costUsd: 1.86,
-  tokensConsumed: 1_400_000,
+  updatedAt: '2026-06-14T12:00:00.000Z',
+  usage: usage(1.86),
+  // Present by default so `delete record.banked` in the legacy-row cases actually removes
+  // something, and so the storage round-trip covers it.
+  banked: usage(0.5),
   models: [{ model: 'claude-sonnet-4-6', provider: 'anthropic' }],
   ...overrides,
 });
@@ -28,23 +41,90 @@ suite('uses a scoped storage key', () => {
   assert.is(costHistoryStorageKey('my-app'), 'genesis-ai-assistant:cost-history:my-app');
 });
 
-suite('persists and loads records newest-first via append', () => {
+suite('upsertRecord prepends a project it has not seen', () => {
+  const first = upsertRecord([], sampleRecord({ id: 'a', projectKey: 'a', title: 'First' }));
+  const both = upsertRecord(first, sampleRecord({ id: 'b', projectKey: 'b', title: 'Second' }));
+  assert.is(both.length, 2);
+  // Insertion order, not recency — display ordering is sortRecordsByRecency's job.
+  assert.is(both[0]?.id, 'b', 'most recently added is prepended');
+  assert.is(both[1]?.id, 'a');
+});
+
+suite('upsertRecord replaces a project in place rather than stacking a second row', () => {
+  const seeded = [
+    sampleRecord({ id: 'b', projectKey: 'b', usage: usage(2) }),
+    sampleRecord({ id: 'a', projectKey: 'a', usage: usage(1) }),
+  ];
+  // Re-reporting a project must REPLACE its row. Appending here is what made a single
+  // project's spend count once per refresh in any total summed over the list.
+  const next = upsertRecord(seeded, sampleRecord({ id: 'a', projectKey: 'a', usage: usage(9.5) }));
+  assert.is(next.length, 2);
+  // Replaced in place rather than moved — the stored array is not a recency ordering.
+  assert.is(next[1]?.projectKey, 'a');
+  assert.is(next[1]?.usage.costUsd, 9.5);
+  assert.is(
+    next.reduce((sum, r) => sum + r.usage.costUsd, 0),
+    11.5,
+  );
+});
+
+suite('round-trips records through storage', () => {
   clearCostSessionHistory(scope);
-  appendCostSessionRecord(scope, sampleRecord({ id: 'a', title: 'First' }));
-  appendCostSessionRecord(scope, sampleRecord({ id: 'b', title: 'Second' }));
+  const records = upsertRecord([], sampleRecord({ id: 'a', projectKey: 'a', usage: usage(3.5) }));
+  saveCostSessionHistory(scope, records);
   const loaded = loadCostSessionHistory(scope);
-  assert.is(loaded.length, 2);
-  assert.is(loaded[0]?.id, 'b');
-  assert.is(loaded[1]?.id, 'a');
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.usage.costUsd, 3.5);
+  assert.is(loaded[0]?.usage.cacheReadTokens, 1_200_000, 'buckets survive serialization');
+  assert.is(loaded[0]?.banked?.costUsd, 0.5, 'banked survives serialization');
   clearCostSessionHistory(scope);
 });
 
-suite('removes one record by id', () => {
+suite('discards legacy rows that predate the per-project key', () => {
   clearCostSessionHistory(scope);
-  saveCostSessionHistory(scope, [sampleRecord({ id: 'keep' }), sampleRecord({ id: 'drop' })]);
-  const remaining = removeCostSessionRecord(scope, 'drop');
-  assert.is(remaining.length, 1);
-  assert.is(remaining[0]?.id, 'keep');
+  const legacy = sampleRecord({ id: 'old' }) as Partial<CostSessionRecord>;
+  delete legacy.projectKey;
+  saveCostSessionHistory(scope, [legacy as CostSessionRecord, sampleRecord({ id: 'new' })]);
+  const loaded = loadCostSessionHistory(scope);
+  // A keyless row can never be matched to a project, so pooling it with the new rows
+  // would permanently double-count whichever project it came from.
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.id, 'new');
+  clearCostSessionHistory(scope);
+});
+
+suite('discards rows whose usage is not fully numeric', () => {
+  clearCostSessionHistory(scope);
+  const broken = sampleRecord({ id: 'broken' });
+  // A half-shaped `usage` is worse than a missing row: it sums as NaN and poisons every
+  // total on the Usage tab, with no clue where the NaN came from.
+  delete (broken.usage as Partial<CostSessionRecord['usage']>).outputTokens;
+  saveCostSessionHistory(scope, [broken, sampleRecord({ id: 'ok', projectKey: 'ok' })]);
+  const loaded = loadCostSessionHistory(scope);
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.id, 'ok');
+  clearCostSessionHistory(scope);
+});
+
+suite('discards rows whose banked figure is half-shaped', () => {
+  clearCostSessionHistory(scope);
+  const broken = sampleRecord({ id: 'broken', banked: { ...usage(2) } });
+  // A malformed `banked` poisons the lifetime total exactly as a malformed `usage` does,
+  // since the two are added together to produce it.
+  delete (broken.banked as Partial<CostSessionRecord['usage']>).cacheWriteTokens;
+  saveCostSessionHistory(scope, [broken, sampleRecord({ id: 'ok', projectKey: 'ok' })]);
+  const loaded = loadCostSessionHistory(scope);
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.id, 'ok');
+  clearCostSessionHistory(scope);
+});
+
+suite('keeps a row whose banked figure is absent', () => {
+  clearCostSessionHistory(scope);
+  const legacy = sampleRecord({ id: 'legacy' });
+  delete legacy.banked;
+  saveCostSessionHistory(scope, [legacy]);
+  assert.is(loadCostSessionHistory(scope).length, 1, 'absent is valid, unlike half-shaped');
   clearCostSessionHistory(scope);
 });
 
@@ -52,4 +132,95 @@ suite('formats session dates for display', () => {
   assert.is(formatCostSessionDate('2026-06-14T12:00:00.000Z'), 'Jun 14, 2026');
 });
 
+suite('sortRecordsByRecency puts the most recently worked-on project first', () => {
+  const records = [
+    sampleRecord({ id: 'old', projectKey: 'old', updatedAt: '2026-01-01T00:00:00.000Z' }),
+    sampleRecord({ id: 'newest', projectKey: 'newest', updatedAt: '2026-08-04T09:00:00.000Z' }),
+    sampleRecord({ id: 'mid', projectKey: 'mid', updatedAt: '2026-05-01T00:00:00.000Z' }),
+  ];
+  const sorted = sortRecordsByRecency(records);
+  assert.equal(
+    sorted.map((r) => r.id),
+    ['newest', 'mid', 'old'],
+  );
+  // Read-time ordering, so the caller's array must be left alone.
+  assert.equal(
+    records.map((r) => r.id),
+    ['old', 'newest', 'mid'],
+    'input not mutated',
+  );
+});
+
+suite('sortRecordsByRecency overrides insertion order, which upsert leaves alone', () => {
+  // The behaviour this fixes: revisiting a project replaces its row IN PLACE, so insertion order
+  // strands it wherever it was first seen. Display order must come from updatedAt instead.
+  let records = upsertRecord(
+    [],
+    sampleRecord({ id: 'a', projectKey: 'a', updatedAt: '2026-01-01T00:00:00.000Z' }),
+  );
+  records = upsertRecord(
+    records,
+    sampleRecord({ id: 'b', projectKey: 'b', updatedAt: '2026-02-01T00:00:00.000Z' }),
+  );
+  // Work on 'a' again — newer than 'b', but upsert keeps it in slot 1.
+  records = upsertRecord(
+    records,
+    sampleRecord({ id: 'a', projectKey: 'a', updatedAt: '2026-03-01T00:00:00.000Z' }),
+  );
+  assert.is(records[1]?.id, 'a', 'stored order is unchanged by the revisit');
+  assert.is(sortRecordsByRecency(records)[0]?.id, 'a', 'display order tracks the revisit');
+});
+
+suite('banks nothing for a project with no prior row', () => {
+  assert.equal(resolveBankedUsage(undefined, true), emptyUsage());
+  assert.equal(resolveBankedUsage(undefined, false), emptyUsage());
+});
+
+suite('carries the prior banked figure forward when the transcript is authoritative', () => {
+  // Restored transcript: it already re-proves everything after the row's own banked figure,
+  // so only that figure carries over. Taking `usage` here is the compounding double-count.
+  const prior = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  assert.is(resolveBankedUsage(prior, true).costUsd, 4);
+});
+
+suite('banks the whole prior total when the transcript starts empty', () => {
+  // Nothing on screen accounts for the previous total, so all of it must carry over or the
+  // next turn rewrites the row down to just that turn.
+  const prior = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  assert.is(resolveBankedUsage(prior, false).costUsd, 10);
+});
+
+suite('treats a row predating the banked field as nothing banked', () => {
+  const legacy = sampleRecord({ usage: usage(7) });
+  delete legacy.banked;
+  assert.equal(resolveBankedUsage(legacy, true), emptyUsage());
+  // Without persistence the legacy total still carries, so upgrading loses no spend.
+  assert.is(resolveBankedUsage(legacy, false).costUsd, 7);
+});
+
+suite('is stable across repeated reloads — the regression this guards', () => {
+  // Simulate the reload cycle: usage = banked + whatever the transcript proves. With a
+  // restored transcript (worth 6 on top of 4 banked) the row must land on 10 every time,
+  // not 10 → 14 → 18 as it did when a reload re-banked the restored history.
+  const transcript = 6;
+  let row = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  for (let reload = 0; reload < 3; reload += 1) {
+    const banked = resolveBankedUsage(row, true);
+    row = { ...row, banked, usage: { ...usage(banked.costUsd + transcript) } };
+    assert.is(row.usage.costUsd, 10, `reload ${reload}`);
+  }
+});
+
+suite('accumulates across reloads when the transcript does not persist', () => {
+  // The mirror case: each page-load starts from an empty transcript, so the row must grow by
+  // whatever that load spends rather than being overwritten by it.
+  let row = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  for (const spend of [2, 3]) {
+    const banked = resolveBankedUsage(row, false);
+    row = { ...row, banked, usage: { ...usage(banked.costUsd + spend) } };
+  }
+  // 10 banked, +2 → 12; then 12 banked, +3 → 15. Never decreases.
+  assert.is(row.usage.costUsd, 15);
+});
+
 suite.run();