@cat-factory/app 0.167.1 → 0.169.0

package/app/modular/nav-contributions.ts

@@ -60,6 +60,12 @@ export interface NavGates {
   accountsEnabled: boolean
   /** The caller is an admin of the active account. */
   isAccountAdmin: boolean
+  /**
+   * The interface tier is `advanced` (see `stores/uiMode.ts`). Read by
+   * {@link navSlotFilter} for every {@link NavContribution.advanced} item, and
+   * available to a `gate` predicate that needs to combine it with something else.
+   */
+  advancedMode: boolean
 }
 
 /** Command-palette placement + copy for a contribution that appears in the palette. */
@@ -98,6 +104,7 @@ export const NAV_ACTIONS = [
   'operatorDashboard',
   'reports',
   'shortcuts',
+  'toggleUiMode',
 ] as const
 
 export type NavActionId = (typeof NAV_ACTIONS)[number]
@@ -111,6 +118,13 @@ export interface NavContribution {
   surfaces: readonly NavSurface[]
   /** Reactive predicate over {@link NavGates}; absent = always visible. */
   gate?: (g: NavGates) => boolean
+  /**
+   * A power-user destination: shown only in ADVANCED interface mode (basic mode is the
+   * everyday surface — see `stores/uiMode.ts`). Declarative rather than folded into
+   * {@link gate}, so an item keeps its RBAC/availability predicate unchanged and the two
+   * axes stay independently assertable. Absent = visible in both tiers.
+   */
+  advanced?: boolean
   /**
    * First-party action id, resolved to a `run()` against the host `ui` store by
    * `useNavContributions`. A consumer module that has its own stores instead
@@ -138,6 +152,14 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  *    previously showed it unconditionally; the account modal only makes sense
  *    with accounts enabled).
  *  - one icon per destination across shells.
+ *
+ * `advanced: true` marks the power-user half, hidden in basic interface mode. The line
+ * drawn here is "would a team shipping their first task open this?": connecting a repo or
+ * an integration, picking models, and the workspace/account settings stay; AUTHORING the
+ * machinery those defaults come from (the pipeline builder, the fragment library, merge
+ * thresholds, service fragment defaults), the experimentation surfaces (sandbox, Kaizen),
+ * the infrastructure/environment plumbing, per-user local models, and the operator-tier
+ * dashboards do not.
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
   {
@@ -145,6 +167,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.buildPipeline',
     icon: 'i-lucide-workflow',
     surfaces: S('sidebar', 'command'),
+    advanced: true,
     gate: (g) => g.canWriteBoard,
     action: 'buildPipeline',
     testId: 'nav-build-pipeline',
@@ -203,6 +226,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.sandbox',
     icon: 'i-lucide-flask-conical',
     surfaces: S('sidebar', 'command'),
+    advanced: true,
     gate: (g) => g.canManageIntegrations,
     action: 'sandbox',
     testId: 'nav-sandbox',
@@ -219,6 +243,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.kaizen',
     icon: 'i-lucide-sparkles',
     surfaces: S('sidebar'),
+    advanced: true,
     action: 'kaizen',
     testId: 'nav-kaizen',
     sidebar: { group: 'integrations', order: 30 },
@@ -228,6 +253,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.infrastructure',
     icon: 'i-lucide-server-cog',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.infrastructureAvailable,
     action: 'infrastructure',
     testId: 'nav-infrastructure',
@@ -238,6 +264,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.environmentSetup',
     icon: 'i-lucide-flask-conical',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.infrastructureAvailable,
     action: 'environmentSetup',
     testId: 'nav-environment-setup',
@@ -248,6 +275,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.contextFragments',
     icon: 'i-lucide-book-marked',
     surfaces: S('sidebar', 'command'),
+    advanced: true,
     gate: (g) => g.libraryAvailable && g.canManageSettings,
     action: 'fragmentLibrary',
     testId: 'nav-fragments',
@@ -264,6 +292,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.mergeThresholds',
     icon: 'i-lucide-git-merge',
     surfaces: S('command'),
+    advanced: true,
     gate: (g) => g.canManageSettings,
     action: 'mergeThresholds',
     command: {
@@ -309,6 +338,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.serviceFragmentDefaults',
     icon: 'i-lucide-book-open-check',
     surfaces: S('command'),
+    advanced: true,
     gate: (g) => g.canManageSettings,
     action: 'serviceFragmentDefaults',
     command: {
@@ -322,6 +352,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.localModels',
     icon: 'i-lucide-server',
     surfaces: S('command'),
+    advanced: true,
     action: 'localModels',
     command: {
       group: 'workspace',
@@ -350,6 +381,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.operatorDashboard',
     icon: 'i-lucide-gauge',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.accountsEnabled && g.isAccountAdmin,
     action: 'operatorDashboard',
     testId: 'nav-operator-dashboard',
@@ -360,6 +392,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.reports',
     icon: 'i-lucide-chart-column',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.accountsEnabled && g.isAccountAdmin,
     action: 'reports',
     testId: 'nav-reports',
@@ -377,6 +410,23 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.shortcuts',
     },
   },
+  {
+    // Deliberately NOT `advanced`: this is the way BACK. Basic mode is the shipped default, so
+    // for most users the sidebar switcher is their first sight of the tier — and in the basic
+    // rail it renders icon-only, which is a thin thread to hang the entire advanced half of the
+    // product on. The palette is reachable in both tiers, searchable by name, and is already
+    // "the primary way to reach every action", so the tier belongs in it.
+    id: 'ui-mode',
+    labelKey: 'layout.commandBar.cmd.toggleUiMode',
+    icon: 'i-lucide-toggle-right',
+    surfaces: S('command'),
+    action: 'toggleUiMode',
+    command: {
+      group: 'workspace',
+      order: 90,
+      keywordsKey: 'layout.commandBar.keywords.toggleUiMode',
+    },
+  },
 ]
 
 /**
@@ -390,10 +440,14 @@ export const navigationModule = defineModule({
 })
 
 /**
- * Reactive RBAC/availability filter over the merged `nav` slot. Reads
+ * Reactive RBAC/availability/interface-tier filter over the merged `nav` slot. Reads
  * `deps.gates.*` (the reactive gate service) per item, so evaluated inside
- * `useReactiveSlots` it re-runs when a permission or connection flips. Passed to
- * `installModularApp` as the global `slotFilter`.
+ * `useReactiveSlots` it re-runs when a permission, connection, or the interface
+ * mode flips. Passed to `installModularApp` as the global `slotFilter`.
+ *
+ * The two axes are independent and BOTH must pass: an `advanced` item is dropped in
+ * basic mode, and every item still answers to its own `gate`. Order doesn't matter
+ * (it's a conjunction) but the tier is checked first, since it's the cheaper read.
  *
  * Typed against `AppSlots` (not the generic `SlotFilter`) so it matches the
  * filter shape the runtime infers for this registry. `deps` is widened to an
@@ -406,7 +460,11 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
     ...slots,
     // No gates service wired (tests / bare install) ⇒ show everything, matching
     // the dev-open "absent access allows all" backend parity.
-    nav: gates ? nav.filter((i) => (i.gate ? i.gate(gates) : true)) : nav,
+    nav: gates
+      ? nav.filter(
+          (i) => (i.advanced ? gates.advancedMode : true) && (i.gate ? i.gate(gates) : true),
+        )
+      : nav,
   }
 }
 

package/app/modular/nav-gates.ts

@@ -13,7 +13,9 @@ import type { NavGates } from '~/modular/nav-contributions'
  * permission or connection flip re-gates every shell with no `recalculateSlots()`.
  *
  * This mirrors the exact gating the pre-slice-1 `SideBar` computeds encoded (see
- * `useWorkspaceAccess` for the dev-open "absent access ⇒ allow all" parity).
+ * `useWorkspaceAccess` for the dev-open "absent access ⇒ allow all" parity), plus
+ * the interface tier (`advancedMode`), which rides the same service so a mode flip
+ * re-gates all three shells through the same reactive path as a permission flip.
  */
 export function createNavGates(): NavGates {
   const access = useWorkspaceAccess()
@@ -22,6 +24,7 @@ export function createNavGates(): NavGates {
   const accounts = useAccountsStore()
   const auth = useAuthStore()
   const providerConnections = useProviderConnectionsStore()
+  const uiMode = useUiModeStore()
 
   const infrastructureAvailable = computed(
     () =>
@@ -59,5 +62,8 @@ export function createNavGates(): NavGates {
     get isAccountAdmin() {
       return isAccountAdmin.value
     },
+    get advancedMode() {
+      return uiMode.isAdvanced
+    },
   }
 }

package/app/modular/registry.spec.ts

@@ -12,6 +12,7 @@ const NO_GATES: NavGates = {
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,
+  advancedMode: false,
 }
 
 describe('app modular registry', () => {

package/app/stores/bugHunt.ts

@@ -1,18 +1,10 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import type { BugHuntResult, RunBugHuntInput, TaskSourceKind, TrackerBoard } from '~/types/domain'
-import { apiErrorEnvelope } from '~/composables/api/errors'
+import { apiErrorReason } from '~/composables/api/errors'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { usePersonalSubscriptionsStore } from '~/stores/personalSubscriptions'
 
-/** The backend's `error.details.reason` code, when it sent one (see `useApi`'s error envelope). */
-function errorReasonOf(error: unknown): string | null {
-  const details = apiErrorEnvelope(error)?.details
-  if (!details || typeof details !== 'object') return null
-  const reason = (details as Record<string, unknown>).reason
-  return typeof reason === 'string' ? reason : null
-}
-
 /**
  * Bug-hunt state: the boards of the tracker being browsed, the last hunt's ranked candidates,
  * and the actions behind the three steps (list boards → run the hunt → adopt one candidate).
@@ -68,7 +60,7 @@ export const useBugHuntStore = defineStore('bugHunt', () => {
       if (boardsSource.value !== source) return
       boards.value = []
       boardsError.value = e instanceof Error ? e.message : String(e)
-      boardsErrorReason.value = errorReasonOf(e)
+      boardsErrorReason.value = apiErrorReason(e)
     } finally {
       boardsLoading.value = false
     }

package/app/stores/tasks.ts

@@ -146,14 +146,17 @@ export const useTasksStore = defineStore('tasks', () => {
 
   /**
    * Search a connected tracker's issues by free text (title/content). `blockId`
-   * (a service frame or a task/module under one) scopes a GitHub search to that
-   * service's linked repo — so hits stay in-repo and a pasted URL / bare issue
-   * number resolves to the exact issue. Omitted → an unscoped workspace search.
+   * (a service frame or a task/module under one) is REQUIRED: it scopes a GitHub
+   * search to that service's linked repo, so hits stay in-repo and a bare issue
+   * number resolves to the exact issue. There is no unscoped mode — an unscoped
+   * GitHub search reaches every repository the backend's credential can see. An
+   * issue in another repo is linked by pasting its URL (the picker's by-reference
+   * row imports it directly instead of searching).
    */
   async function search(
     source: TaskSourceKind,
     query: string,
-    blockId?: string,
+    blockId: string,
   ): Promise<TaskSearchResult[]> {
     const { results } = await api.searchTaskSource(workspace.requireId(), source, query, blockId)
     return results

package/app/stores/uiMode.spec.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { nextTick } from 'vue'
+import { useUiModeStore } from '~/stores/uiMode'
+import type { UiMode } from '~/utils/uiMode'
+
+/**
+ * Point `runtimeConfig.public.uiMode` at a value and hand back a store built against it.
+ * The env value is read ONCE at store setup (it is build-time-baked in a `ssr: false` SPA),
+ * so every case needs a fresh Pinia — which is also what proves the read isn't reactive.
+ */
+function storeWithEnv(uiMode: string | undefined) {
+  vi.stubGlobal('useRuntimeConfig', () => ({ public: { apiBase: '', uiMode } }))
+  setActivePinia(createPinia())
+  return useUiModeStore()
+}
+
+describe('useUiModeStore mode resolution', () => {
+  beforeEach(() => {
+    // The default runtime-config stub carries no `uiMode` at all — the shape a deployment
+    // that never set NUXT_PUBLIC_UI_MODE ends up with once Nuxt applies the '' default.
+    vi.stubGlobal('useRuntimeConfig', () => ({ public: { apiBase: '', uiMode: '' } }))
+  })
+
+  it('boots in basic mode with no env pin and nothing stored', () => {
+    const ui = useUiModeStore()
+    expect(ui.mode).toBe('basic')
+    expect(ui.isAdvanced).toBe(false)
+    expect(ui.envPinned).toBe(false)
+  })
+
+  it('honours the browser-stored choice when no env pin is present', () => {
+    const ui = useUiModeStore()
+    ui.setMode('advanced')
+    expect(ui.mode).toBe('advanced')
+    expect(ui.isAdvanced).toBe(true)
+    // Persisted, so a reload restores it (the persist plugin picks `storedMode`).
+    expect(ui.storedMode).toBe('advanced')
+  })
+
+  it('lets the env pin override a conflicting stored choice, in both directions', () => {
+    const pinnedBasic = storeWithEnv('advanced')
+    pinnedBasic.storedMode = 'basic'
+    expect(pinnedBasic.mode).toBe('advanced')
+
+    const pinnedAdvanced = storeWithEnv('basic')
+    pinnedAdvanced.storedMode = 'advanced'
+    expect(pinnedAdvanced.mode).toBe('basic')
+  })
+
+  it('refuses to record a preference under an env pin', () => {
+    const ui = storeWithEnv('basic')
+    expect(ui.envPinned).toBe(true)
+    ui.setMode('advanced')
+    ui.toggleMode()
+    // Nothing written: the resolver would ignore it, so persisting it would be a lie.
+    expect(ui.storedMode).toBeNull()
+    expect(ui.mode).toBe('basic')
+  })
+
+  it('ignores an unrecognised env value rather than failing the boot', () => {
+    const ui = storeWithEnv('expert')
+    expect(ui.envPinned).toBe(false)
+    expect(ui.mode).toBe('basic')
+    ui.setMode('advanced')
+    expect(ui.mode).toBe('advanced')
+  })
+
+  it('toggleMode flips between the two tiers', () => {
+    const ui = useUiModeStore()
+    ui.toggleMode()
+    expect(ui.mode).toBe('advanced')
+    ui.toggleMode()
+    expect(ui.mode).toBe('basic')
+  })
+})
+
+describe('useUiModeStore navbar collapse', () => {
+  beforeEach(() => {
+    vi.stubGlobal('useRuntimeConfig', () => ({ public: { apiBase: '', uiMode: '' } }))
+  })
+
+  it('starts collapsed in basic mode and expanded in advanced mode', () => {
+    expect(useUiModeStore().navCollapsed).toBe(true)
+
+    const advanced = storeWithEnv('advanced')
+    expect(advanced.navCollapsed).toBe(false)
+  })
+
+  it('remembers the rail choice in EITHER tier, across a reload', () => {
+    // The persisted shape is per-tier, so an expand in basic is remembered just as an advanced
+    // one is — the default is what differs between the tiers, not whether a choice sticks.
+    const ui = useUiModeStore()
+    ui.toggleNav()
+    expect(ui.navCollapsed).toBe(false)
+    expect(ui.railCollapsed.basic).toBe(false)
+
+    const advanced = storeWithEnv('advanced')
+    advanced.toggleNav()
+    expect(advanced.navCollapsed).toBe(true)
+    expect(advanced.railCollapsed.advanced).toBe(true)
+  })
+
+  it('keeps each tier’s rail state independent across a switch', async () => {
+    const ui = useUiModeStore()
+    // Expand in basic, then collapse in advanced: neither choice may leak into the other tier.
+    ui.toggleNav()
+    expect(ui.navCollapsed).toBe(false)
+
+    ui.setMode('advanced')
+    await nextTick()
+    expect(ui.navCollapsed).toBe(false) // advanced's own default
+    ui.toggleNav()
+    expect(ui.navCollapsed).toBe(true)
+
+    ui.setMode('basic')
+    await nextTick()
+    expect(ui.navCollapsed).toBe(false) // the basic expand survived the round trip
+
+    ui.setMode('advanced')
+    await nextTick()
+    expect(ui.navCollapsed).toBe(true)
+  })
+
+  it('falls back to the tier default when the restored preference is missing a key', () => {
+    // A persisted blob from an older build (or a hand-edited cookie) can omit a tier; a rail
+    // stuck on `undefined` would render expanded, which is wrong for basic.
+    const ui = useUiModeStore()
+    ui.railCollapsed = {} as Record<UiMode, boolean>
+    expect(ui.navCollapsed).toBe(true)
+    ui.setMode('advanced')
+    expect(ui.navCollapsed).toBe(false)
+  })
+
+  it('setNavCollapsed is idempotent', () => {
+    const ui = storeWithEnv('advanced')
+    ui.setNavCollapsed(true)
+    ui.setNavCollapsed(true)
+    expect(ui.navCollapsed).toBe(true)
+    ui.setNavCollapsed(false)
+    expect(ui.navCollapsed).toBe(false)
+  })
+})
+
+describe('useUiModeStore typing', () => {
+  it('exposes the mode as the closed union', () => {
+    const ui = useUiModeStore()
+    const mode: UiMode = ui.mode
+    expect(['basic', 'advanced']).toContain(mode)
+  })
+})

package/app/stores/uiMode.ts

@@ -0,0 +1,88 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import { DEFAULT_RAIL_COLLAPSED, parseUiMode, resolveUiMode, type UiMode } from '~/utils/uiMode'
+
+/**
+ * The interface tier (`basic` / `advanced`) and the side-navbar collapse state.
+ *
+ * Mode resolution is `env → browser-stored → basic` (see `utils/uiMode.ts`). The env value
+ * is `runtimeConfig.public.uiMode`, i.e. `NUXT_PUBLIC_UI_MODE`: the SPA is `ssr: false`, so
+ * — exactly like `apiBase` — it is baked in at build time and cannot change while the app
+ * is loaded. It is therefore read ONCE here rather than tracked reactively. Only the user's
+ * own choice is persisted, so a deployment that later drops its env pin falls back to
+ * whatever the user last picked instead of to the default.
+ *
+ * The collapse state is a PER-TIER preference (`railCollapsed`), not a single boolean. The two
+ * tiers want different resting states — basic opens railed, advanced expanded — so one shared
+ * flag can only serve one of them: it would either override the other tier's default or throw
+ * away the user's choice on every switch. Keying the preference by tier gives each its own
+ * default (`DEFAULT_RAIL_COLLAPSED`) AND its own memory, so switching tiers restores what that
+ * tier last looked like and neither has to forget. That is also why there is no watcher here:
+ * the collapse follows `mode` because it is indexed by it, not because something resets on
+ * change.
+ */
+export const useUiModeStore = defineStore(
+  'uiMode',
+  () => {
+    const envMode = parseUiMode(useRuntimeConfig().public.uiMode)
+
+    /** The user's explicit pick, persisted. `null` until they choose one. */
+    const storedMode = ref<UiMode | null>(null)
+    /** The rail state each tier was last left in, persisted. Seeded from the per-tier defaults. */
+    const railCollapsed = ref<Record<UiMode, boolean>>({ ...DEFAULT_RAIL_COLLAPSED })
+
+    const mode = computed<UiMode>(() => resolveUiMode(envMode, storedMode.value))
+    const isAdvanced = computed(() => mode.value === 'advanced')
+    /** Pinned by the deployment: the switcher is read-only, since a write would be ignored. */
+    const envPinned = computed(() => envMode !== null)
+
+    // `?? the default` because the restored value is untrusted input, exactly like the env
+    // string: a persisted blob written by an older build (or hand-edited) can be missing this
+    // tier's key, and a rail stuck on `undefined` would render as expanded in basic mode.
+    const navCollapsed = computed(
+      () => railCollapsed.value[mode.value] ?? DEFAULT_RAIL_COLLAPSED[mode.value],
+    )
+
+    /**
+     * Record the user's pick. A no-op under an env pin — the resolver would ignore it.
+     *
+     * This guard is hygiene, not the invariant. `storedMode` is returned from the store because
+     * a setup store can only persist what it returns (as in `auth`, `accounts`, `workspace`), so
+     * a caller CAN write it directly and skip this check. That is harmless by construction:
+     * `mode` runs `resolveUiMode(env, stored)`, which consults the env pin FIRST, so a direct
+     * write can leave a stale persisted value but can never change the tier under a pin. The
+     * "env pin wins, in both directions" case above is what actually pins that.
+     */
+    function setMode(next: UiMode) {
+      if (envPinned.value) return
+      storedMode.value = next
+    }
+
+    function toggleMode() {
+      setMode(isAdvanced.value ? 'basic' : 'advanced')
+    }
+
+    /** Remember the rail state for the CURRENT tier; the other tier keeps its own. */
+    function setNavCollapsed(collapsed: boolean) {
+      railCollapsed.value = { ...railCollapsed.value, [mode.value]: collapsed }
+    }
+
+    function toggleNav() {
+      setNavCollapsed(!navCollapsed.value)
+    }
+
+    return {
+      mode,
+      isAdvanced,
+      envPinned,
+      storedMode,
+      railCollapsed,
+      navCollapsed,
+      setMode,
+      toggleMode,
+      setNavCollapsed,
+      toggleNav,
+    }
+  },
+  { persist: { pick: ['storedMode', 'railCollapsed'] } },
+)

package/app/utils/observability.spec.ts

@@ -1,28 +1,28 @@
 import { describe, it, expect } from 'vitest'
-import { freshPromptTokens } from './observability'
+import { totalInputTokens } from './observability'
 
-describe('freshPromptTokens', () => {
-  it('subtracts the cached prefix from the prompt-token sum', () => {
-    expect(freshPromptTokens(1000, 300)).toBe(700)
+describe('totalInputTokens', () => {
+  it('sums all three input classes, so the headline matches Claude Code’s context gauge', () => {
+    expect(
+      totalInputTokens({ promptTokens: 685, cacheReadTokens: 31_099_813, cacheWriteTokens: 0 }),
+    ).toBe(31_100_498)
   })
 
-  it('reduces a near-fully-cached agentic run to its tiny fresh input (inclusive shape)', () => {
-    // The 31M-cache-read shape from the investigation on the INCLUSIVE shape (subscription
-    // harness / OpenAI-style): prompt tokens INCLUDE the cache reads, so subtracting the cached
-    // subset leaves the few-hundred-token fresh figure, not tens of millions.
-    expect(freshPromptTokens(31_100_498, 31_099_813)).toBe(685)
+  it('counts cache WRITES too — they occupy the window like any other input token', () => {
+    expect(
+      totalInputTokens({ promptTokens: 100, cacheReadTokens: 900, cacheWriteTokens: 40 }),
+    ).toBe(1040)
   })
 
-  it('treats promptTokens as already-fresh when cached exceeds it (Anthropic separate shape)', () => {
-    // Anthropic via the LLM proxy reports cache reads SEPARATELY, so promptTokens is fresh-only
-    // and cachedPromptTokens can far exceed it. The fresh figure is promptTokens itself — NOT 0
-    // (the old subtract-and-clamp collapsed real fresh input to zero on this shape).
-    expect(freshPromptTokens(685, 31_099_813)).toBe(685)
+  it('does NOT lead with the fresh figure on a cache-dominated run', () => {
+    // The regression this pins: leading with fresh made a ~31M-token run render as 685 tokens,
+    // discounting cache reads because their dollar cost is low. Volume is the thing being
+    // measured here, and a cached token costs the same context window as a fresh one.
+    const m = { promptTokens: 685, cacheReadTokens: 31_099_813, cacheWriteTokens: 0 }
+    expect(totalInputTokens(m)).toBeGreaterThan(m.promptTokens * 1000)
   })
 
-  it('never returns negative, and treats a fully-cached inclusive rollup as 0 fresh', () => {
-    expect(freshPromptTokens(500, 500)).toBe(0)
-    // cached > prompt ⇒ separate shape ⇒ fresh = prompt (never a negative number).
-    expect(freshPromptTokens(500, 600)).toBe(500)
+  it('degrades to the fresh count when an older snapshot carries no cache fields', () => {
+    expect(totalInputTokens({ promptTokens: 500 })).toBe(500)
   })
 })

package/app/utils/observability.ts

@@ -12,31 +12,28 @@ export function formatTokens(n: number): string {
 }
 
 /**
- * FRESH (uncached) prompt tokens: the input tokens actually processed this call/rollup after
- * excluding the prefix served from the provider's cache. A long agentic run re-sends its whole
- * growing transcript every turn, so on the "inclusive" shape the raw `promptTokens` sum is
- * dominated by cache reads (often >99%) — showing THAT as "tokens burned" reads as a blow-up
- * when almost nothing fresh was processed. This surfaces the fresh figure alongside cached.
+ * TOTAL input tokens: fresh + cache read + cache write. This is the headline "↑" figure on
+ * every LLM surface, and it deliberately COUNTS THE CACHED CLASSES.
  *
- * `cachedPromptTokens` has PROVIDER-DEPENDENT semantics (see the field docs on `stepMetricsSchema`
- * / `llmCallMetricSchema`), so we can't blindly subtract:
- *  - Inclusive shape (OpenAI/DeepSeek, and the subscription-CLI harness, which folds cache into
- *    `promptTokens`): cached is a SUBSET of prompt ⇒ fresh = prompt − cached.
- *  - Separate shape (Anthropic via the LLM proxy): cache reads are reported SEPARATELY and
- *    `promptTokens` is ALREADY fresh-only, so cached can EXCEED prompt. Subtracting there would
- *    wrongly collapse a real fresh input to 0 — when cached ≥ prompt, `promptTokens` itself IS
- *    the fresh figure.
+ * That is the like-for-like measure of Claude Code's own context gauge, which sums exactly these
+ * buckets because a cached token still physically occupies the context window. Leading with the
+ * fresh figure instead (what this surface used to do, on the grounds that the raw sum "reads as a
+ * blow-up") discounts cache reads because their DOLLAR cost is low — but the quota, latency and
+ * context-window cost is the whole thing an autonomous run burns, and hiding it is what let a
+ * ~31M-token run look like a 685-token one. See
+ * `docs/initiatives/token-burn-instrumentation.md`.
  *
- * NOTE: with only these two aggregates we cannot distinguish the separate shape while cached is
- * still ≤ prompt (there the subtraction under-counts fresh by the cache-read amount). A fully
- * exact split needs the wire contract to carry cache-read vs cache-write distinctly at the
- * source; this heuristic fixes the dominant (cached ≫ prompt) case and never returns negative.
+ * The three classes are still rendered as the breakdown beneath it, because they are priced an
+ * order of magnitude apart in opposite directions — this makes the volume honest WITHOUT making
+ * the cost unreadable. The two fields are optional on an older snapshot, where absent reads as 0
+ * and the total degrades to the fresh count.
  */
-export function freshPromptTokens(promptTokens: number, cachedPromptTokens: number): number {
-  // Separate shape: promptTokens is already fresh-only (cache reads counted separately).
-  if (cachedPromptTokens > promptTokens) return promptTokens
-  // Inclusive shape: cached is a subset of prompt.
-  return promptTokens - cachedPromptTokens
+export function totalInputTokens(m: {
+  promptTokens: number
+  cacheReadTokens?: number
+  cacheWriteTokens?: number
+}): number {
+  return m.promptTokens + (m.cacheReadTokens ?? 0) + (m.cacheWriteTokens ?? 0)
 }
 
 /** Compact duration: 850 → "850ms", 1500 → "1.5s", 90_000 → "1m 30s". */