@cat-factory/app 0.213.1 → 0.214.0

package/app/stores/tutorial.spec.ts

@@ -121,10 +121,16 @@ describe('useTutorialStore catalogue', () => {
     tutorial.setStepIndex(2)
     tutorial.stopTour()
 
+    tutorial.offerNudge('answer-park')
     tutorial.resetProgress()
     expect(tutorial.completedTourIds).toEqual([])
     expect(tutorial.interruptedAt('run-task')).toBeNull()
     expect(tutorial.decision).toBeNull()
+    // The spent contextual offers go too, or a board that has already run something would
+    // never make them again to the colleague the app was just handed to.
+    expect(tutorial.nudgedTourIds).toEqual([])
+    expect(tutorial.pendingNudgeId).toBeNull()
+    expect(tutorial.wasNudged('answer-park')).toBe(false)
   })
 
   it('leaves a running tour alone when progress is reset', () => {
@@ -300,3 +306,204 @@ describe('useTutorialStore resuming a broken-off tour', () => {
     expect(tutorial.interruptedAt('gone-away')).toBeNull()
   })
 })
+
+describe('useTutorialStore contextual offer', () => {
+  it('raises the offer and spends the id in one act', () => {
+    // The guard against re-offering is the PERSISTED list, not the visible state, so an offer
+    // cannot be made twice however many times the live gates flip.
+    const tutorial = useTutorialStore()
+    tutorial.offerNudge('answer-park')
+    expect(tutorial.pendingNudgeId).toBe('answer-park')
+    expect(tutorial.wasNudged('answer-park')).toBe(true)
+  })
+
+  it('never re-raises an offer already spent, even once dismissed', () => {
+    const tutorial = useTutorialStore()
+    tutorial.offerNudge('answer-park')
+    tutorial.dismissNudge()
+    expect(tutorial.pendingNudgeId).toBeNull()
+    tutorial.offerNudge('answer-park')
+    expect(tutorial.pendingNudgeId).toBeNull()
+    expect(tutorial.nudgedTourIds).toEqual(['answer-park'])
+  })
+
+  it('holds one offer at a time, keeping the newer arrival', () => {
+    const tutorial = useTutorialStore()
+    tutorial.offerNudge('answer-park')
+    tutorial.offerNudge('diagnose-failure')
+    expect(tutorial.pendingNudgeId).toBe('diagnose-failure')
+    expect(tutorial.nudgedTourIds).toEqual(['answer-park', 'diagnose-failure'])
+  })
+})
+
+describe('useTutorialStore server reconciliation', () => {
+  it('unions the server copy into the local one, keeping what only this browser knew', () => {
+    // Both lists are grow-only sets of things that HAPPENED, so neither side may un-say one. A
+    // replace here loses a tour finished while the mirror write was failing.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    const pushNeeded = tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: ['first-task'],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.completedTourIds).toEqual(['first-task', 'board-basics'])
+    // This browser held something the server did not, so the mirror owes it a write.
+    expect(pushNeeded).toBe(true)
+    expect(tutorial.serverPushNeeded).toBe(true)
+  })
+
+  it('asks for no push when the server copy is already a superset', () => {
+    // The ordinary reload. Writing anyway would mean every board load posted a mirror nobody reads.
+    const tutorial = useTutorialStore()
+    expect(
+      tutorial.mergeServerProgress({
+        decision: 'accepted',
+        completedTourIds: ['board-basics'],
+        nudgedTourIds: ['answer-park'],
+      }),
+    ).toBe(false)
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+
+  it('never duplicates an id both sides already hold', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.mergeServerProgress({
+      decision: null,
+      completedTourIds: ['board-basics'],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+  })
+
+  it('takes the server decision, but never clears a local one with an absent row', () => {
+    // The decision is a preference someone re-answers, so the shared record wins when it has an
+    // answer. A server row with no answer is not evidence that the local answer never happened.
+    const tutorial = useTutorialStore()
+    tutorial.decline()
+    tutorial.markServerPushed()
+    tutorial.mergeServerProgress({
+      decision: null,
+      completedTourIds: [],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.decision).toBe('declined')
+    expect(tutorial.serverPushNeeded).toBe(true)
+
+    tutorial.markServerPushed()
+    tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: [],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.decision).toBe('accepted')
+  })
+
+  it('holds an UN-MIRRORED local answer against the server, so a failed push cannot undo it', () => {
+    // The mirror is best-effort, so a decline can be sitting in this browser and nowhere else. If
+    // the snapshot re-adopted the older server answer, "No thanks" would silently come back as
+    // "accepted" and every contextual offer the user just declined would re-arm.
+    const tutorial = useTutorialStore()
+    tutorial.decline()
+    expect(
+      tutorial.mergeServerProgress({
+        decision: 'accepted',
+        completedTourIds: [],
+        nudgedTourIds: [],
+      }),
+    ).toBe(true)
+    expect(tutorial.decision).toBe('declined')
+
+    // Once the answer HAS been mirrored, the shared record is authoritative again: another machine
+    // re-answering is a real change, and this browser has nothing newer to defend.
+    tutorial.markServerPushed()
+    tutorial.mergeServerProgress({ decision: 'accepted', completedTourIds: [], nudgedTourIds: [] })
+    expect(tutorial.decision).toBe('accepted')
+  })
+
+  it('treats an absent server copy as nothing to reconcile, not as an empty one', () => {
+    // No accounts, no store wired, or a degraded read. Pushing here would write a mirror on a
+    // deployment that has nowhere to put it; clearing would be worse.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    expect(tutorial.mergeServerProgress(null)).toBe(false)
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+
+  it('clears the push request once the mirror has caught up', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.mergeServerProgress({ decision: null, completedTourIds: [], nudgedTourIds: [] })
+    expect(tutorial.serverPushNeeded).toBe(true)
+    tutorial.markServerPushed()
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+
+  it('re-arms the push when a merge RESPONSE comes back missing something local', () => {
+    // What makes the server's un-guarded merge safe. Two concurrent merges can lose one writer's
+    // ids, and the loser finds out because the response it gets back is a row without them. The
+    // ordering is the load-bearing part: the push is marked done FIRST, so re-arming flips the flag
+    // and re-triggers the mirror rather than being swallowed by a later clear.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.markServerPushed()
+    expect(tutorial.serverPushNeeded).toBe(false)
+    tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: ['first-task'],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.serverPushNeeded).toBe(true)
+  })
+})
+
+describe('useTutorialStore local revision (what the mirror watches)', () => {
+  it('counts only what the USER did, never what the server told us', () => {
+    // The mirror watches this instead of the state, because adopting the server's own ids is a
+    // state change too: watching the state posts the server's row straight back at it on every
+    // fresh-browser board load.
+    const tutorial = useTutorialStore()
+    const before = tutorial.localRev
+    tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: ['board-basics', 'first-task'],
+      nudgedTourIds: ['answer-park'],
+    })
+    expect(tutorial.completedTourIds).toEqual(['board-basics', 'first-task'])
+    expect(tutorial.localRev).toBe(before)
+
+    tutorial.startTour('run-task')
+    tutorial.completeTour()
+    expect(tutorial.localRev).toBeGreaterThan(before)
+  })
+
+  it('does not bump on a re-recorded completion, an unchanged answer, or a reset', () => {
+    const tutorial = useTutorialStore()
+    // Two real changes: the accept `startTour` writes, and the completion.
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    const settled = tutorial.localRev
+    expect(settled).toBe(2)
+
+    // Repeating the same tour changes nothing that is persisted: the answer is already 'accepted'
+    // and the completion is already recorded, so there is nothing for the mirror to carry.
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    expect(tutorial.localRev).toBe(settled)
+
+    // A reset's server side is a DELETE. A push of the freshly-emptied state racing it would
+    // re-create the row the DELETE removed, leaving "reset it" distinguishable from "never touched
+    // the tutorial" — the one thing the reset has to get right.
+    tutorial.resetProgress()
+    expect(tutorial.localRev).toBe(settled)
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+})

package/app/stores/tutorial.ts

@@ -1,41 +1,46 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { createTutorialPrompt } from '~/stores/tutorial.prompt'
+import { createTutorialRecord } from '~/stores/tutorial.record'
 
-/** The launch-prompt answer. `null` = never answered, so the app asks again next launch. */
-export type TutorialDecision = 'accepted' | 'declined'
+// `TutorialDecision` is deliberately NOT re-exported from here even though it used to live here:
+// both store modules are auto-import sources, so two exports of one name make Nuxt drop one of them
+// with a build warning. It is reachable unqualified anywhere in the layer, from `tutorial.record.ts`
+// where it is declared beside the state it describes.
 
 /**
  * The in-app tutorial state: the launch-prompt decision, per-tour completion, and the
  * live progress of whichever tour is running.
  *
- * Two tiers of state, split on purpose:
+ * Two tiers of state, split on purpose — and the split is now a real seam rather than a comment:
  *
- *  - PERSISTED (`decision`, `completedTourIds`) — the user's explicit answer to "would you
- *    like a tour?" and which tours they have finished. Browser-persisted like the interface
- *    tier (`uiMode`): it is a per-person, per-browser preference, and `null` (never asked)
- *    is a real state distinct from `declined` — only an explicit answer stops the launch
- *    prompt from returning, while closing it without answering merely defers it to the
- *    next launch.
- *  - SESSION-ONLY (`promptOpen`, `catalogueOpen`, `activeTourId`, `stepIndex`) — a tour is anchored to live
- *    DOM, so replaying progress across a reload would point step N at a board that hasn't
- *    reached that state; a reloaded tour restarts from its beginning instead.
+ *  - PERSISTED (`decision`, `completedTourIds`, `nudgedTourIds`) — the standing record of what this
+ *    PERSON has done, owned by `createTutorialRecord` (`stores/tutorial.record.ts`) along with the
+ *    server-reconciliation rules that go with it. `null` (never asked) is a real state distinct from
+ *    `declined`: only an explicit answer stops the launch prompt returning, while closing it without
+ *    answering merely defers it to the next launch.
+ *  - SESSION-ONLY (`promptOpen`, `catalogueOpen`, `activeTourId`, `stepIndex`, `pendingNudgeId`) —
+ *    owned here. A tour is anchored to live DOM, so replaying progress across a reload would point
+ *    step N at a board that hasn't reached that state; a reloaded tour restarts from its beginning.
+ *
+ * The persisted half is a per-person fact rather than a per-browser one, so it is MIRRORED to the
+ * signed-in user's server row when the deployment has accounts (`useTutorialSync`), with this store
+ * staying the local cache the SPA reads. Persisting it here as well is not redundancy: it is what a
+ * deployment with auth disabled, and every load before the snapshot lands, runs on.
  *
  * The store deliberately knows nothing about WHICH tours exist: the catalog lives in the
- * `tutorialTours` slot (see `modular/tutorial-tours.ts`), so tours ship and evolve — first-
- * party and consumer-contributed alike — without this store changing. It tracks ids and a
- * step cursor; the overlay resolves definitions and drives the cursor.
+ * `tutorialTours` slot (see `modular/tutorial-tours.ts`), so tours ship and evolve — first-party and
+ * consumer-contributed alike — without this store changing. It tracks ids and a step cursor; the
+ * overlay resolves definitions and drives the cursor.
  */
 export const useTutorialStore = defineStore(
   'tutorial',
   () => {
-    /** The saved launch-prompt answer. Written only by an explicit accept/decline/start. */
-    const decision = ref<TutorialDecision | null>(null)
-    /** Ids of tours the user finished (reached the last step's Done), persisted. */
-    const completedTourIds = ref<string[]>([])
-
-    const promptOpen = ref(false)
-    /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
-    const promptAutoOpened = ref(false)
+    const record = createTutorialRecord()
+    // The launch offer's own four-exit state machine (`stores/tutorial.prompt.ts`), which needs to
+    // know only WHETHER an answer exists.
+    const prompt = createTutorialPrompt({ hasDecision: () => record.decision.value !== null })
+    const { promptOpen } = prompt
     /**
      * The tutorial catalogue (every tour this deployment ships, startable at any time) is
      * open. Always user-driven — nothing auto-opens it — which is why it carries none of the
@@ -58,6 +63,21 @@ export const useTutorialStore = defineStore(
      */
     const interrupted = ref<{ tourId: string; stepIndex: number } | null>(null)
 
+    /**
+     * The tour the contextual offer is currently holding out, or null.
+     *
+     * Session state, and separate from `nudgedTourIds` on purpose: the id is marked as SPENT the
+     * moment the offer is made, while what is on SCREEN survives being suppressed. The two most
+     * valuable moments to offer a tour (a run parked, a run failed) routinely arrive while a
+     * tutorial window or another tour is up, and dropping the offer there would lose the one chance
+     * this mechanism gets. Holding it means it appears as soon as the way is clear.
+     *
+     * The trade is deliberate: a reload before it is ever shown burns the offer. That beats the
+     * alternative of re-arming it, which turns one missed moment into a prompt that keeps coming
+     * back on a board whose gates flip constantly.
+     */
+    const pendingNudgeId = ref<string | null>(null)
+
     /** A tour is currently running (the overlay mounts off this). */
     const touring = computed(() => activeTourId.value !== null)
 
@@ -77,43 +97,6 @@ export const useTutorialStore = defineStore(
      */
     const ownWindowOpen = computed(() => promptOpen.value || catalogueOpen.value)
 
-    /**
-     * Auto-open the launch prompt, at most once per session and only while the user has
-     * never answered it. Callers gate on the rest of the launch context (board ready, no
-     * other startup advisory open) — see `pages/index.vue`.
-     */
-    function maybeOfferOnLaunch() {
-      if (decision.value !== null || promptAutoOpened.value) return
-      promptAutoOpened.value = true
-      promptOpen.value = true
-    }
-
-    /** User-driven open (command palette), regardless of any saved decision. */
-    function openPrompt() {
-      promptOpen.value = true
-    }
-
-    /**
-     * Withdraw an offer this store made, because something the user actually has to answer
-     * (a startup advisory, the GitHub onboarding gate) opened on top of it — and re-arm, so
-     * the offer returns once that surface is gone. Distinct from {@link closePrompt}: no
-     * decision is written EITHER way, but a deferral was not the user's doing, so it must
-     * not consume this session's one offer.
-     *
-     * Only ever withdraws the auto-opened prompt; a prompt the user opened themselves from
-     * the palette is theirs to close.
-     */
-    function deferPrompt() {
-      if (!promptAutoOpened.value) return
-      promptOpen.value = false
-      promptAutoOpened.value = false
-    }
-
-    /** Close without answering: no decision is written, so the next launch asks again. */
-    function closePrompt() {
-      promptOpen.value = false
-    }
-
     /**
      * Open the catalogue. Closes the launch prompt WITHOUT answering it: browsing the full
      * list is not "no thanks" (it is the opposite), and the two are modals that would
@@ -131,7 +114,7 @@ export const useTutorialStore = defineStore(
 
     /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
     function decline() {
-      decision.value = 'declined'
+      record.declineOffer()
       promptOpen.value = false
     }
 
@@ -141,7 +124,7 @@ export const useTutorialStore = defineStore(
      * leaving `declined` in place would misdescribe what happened).
      */
     function startTour(tourId: string) {
-      decision.value = 'accepted'
+      record.acceptOffer()
       promptOpen.value = false
       catalogueOpen.value = false
       activeTourId.value = tourId
@@ -171,7 +154,7 @@ export const useTutorialStore = defineStore(
         startTour(tourId)
         return
       }
-      decision.value = 'accepted'
+      record.acceptOffer()
       promptOpen.value = false
       catalogueOpen.value = false
       activeTourId.value = tourId
@@ -211,9 +194,7 @@ export const useTutorialStore = defineStore(
     /** Finish the running tour: record completion (idempotent) and clear the cursor. */
     function completeTour() {
       const id = activeTourId.value
-      if (id && !completedTourIds.value.includes(id)) {
-        completedTourIds.value = [...completedTourIds.value, id]
-      }
+      if (id) record.markCompleted(id)
       // A finished tour has no position left to resume, and an offer to resume the walkthrough
       // the user just completed would sit beside its own Completed badge.
       if (id !== null && interrupted.value?.tourId === id) interrupted.value = null
@@ -225,45 +206,50 @@ export const useTutorialStore = defineStore(
       return interrupted.value?.tourId === tourId ? interrupted.value.stepIndex : null
     }
 
-    function isCompleted(tourId: string): boolean {
-      return completedTourIds.value.includes(tourId)
+    /**
+     * Hold out the contextual offer for a tour that just became takeable.
+     *
+     * Spending the id and raising the offer are ONE action, so an offer can never be made twice
+     * however many times the gates flip: the guard is the persisted list, not the visible state.
+     * Idempotent, so a caller re-evaluating the catalogue needs no check of its own.
+     */
+    function offerNudge(tourId: string) {
+      if (record.wasNudged(tourId)) return
+      record.markNudged(tourId)
+      pendingNudgeId.value = tourId
+    }
+
+    /** Take the offer off screen. It is already spent, so it does not come back. */
+    function dismissNudge() {
+      pendingNudgeId.value = null
     }
 
     /**
-     * Forget everything this browser remembers about the tutorial: which tours were finished,
-     * where one was broken off, and the answer to the launch offer.
-     *
-     * The decision goes with it deliberately. "Reset" is asked for by someone handing the app
-     * to a colleague, demoing it, or re-walking the product after it changed — and every one
-     * of those wants the first-launch experience back, which a cleared completion list alone
-     * does not restore. It does NOT re-open the prompt in this session: `promptAutoOpened` is
-     * session state and stays spent, so the offer returns at the next launch rather than
-     * appearing on top of the catalogue the user is still reading.
+     * Forget everything this browser remembers about the tutorial (see `record.reset`), plus the
+     * offer currently on screen.
      *
-     * A running tour is left alone: this clears a record, it does not interrupt a walkthrough
-     * the user is in the middle of (which would end it, unrecorded, on a click about history).
+     * It does NOT re-open the prompt in this session: `promptAutoOpened` is session state and stays
+     * spent, so the offer returns at the next launch rather than appearing on top of the catalogue
+     * the user is still reading. A running tour is left alone: this clears a record, it does not
+     * interrupt a walkthrough the user is in the middle of (which would end it, unrecorded, on a
+     * click about history).
      */
     function resetProgress() {
-      completedTourIds.value = []
+      record.reset()
       interrupted.value = null
-      decision.value = null
+      pendingNudgeId.value = null
     }
 
     return {
-      decision,
-      completedTourIds,
-      promptOpen,
-      promptAutoOpened,
+      ...record,
+      ...prompt,
       catalogueOpen,
       activeTourId,
       stepIndex,
       interrupted,
+      pendingNudgeId,
       touring,
       ownWindowOpen,
-      maybeOfferOnLaunch,
-      openPrompt,
-      closePrompt,
-      deferPrompt,
       openCatalogue,
       closeCatalogue,
       resetProgress,
@@ -273,9 +259,10 @@ export const useTutorialStore = defineStore(
       setStepIndex,
       stopTour,
       completeTour,
-      isCompleted,
       interruptedAt,
+      offerNudge,
+      dismissNudge,
     }
   },
-  { persist: { pick: ['decision', 'completedTourIds'] } },
+  { persist: { pick: ['decision', 'completedTourIds', 'nudgedTourIds'] } },
 )

package/app/stores/workspace/hydrate.ts

@@ -25,6 +25,7 @@ import { useSharedStacksStore } from '~/stores/sharedStacks'
 import { useSkillsStore } from '~/stores/skills'
 import { useTaskTypesStore } from '~/stores/taskTypes'
 import { useTrackerStore } from '~/stores/tracker'
+import { useTutorialStore } from '~/stores/tutorial'
 import { useWorkspaceSettingsStore } from '~/stores/workspaceSettings'
 import { buildWorkspaceCapabilitiesManifest } from '~/modular/capabilities'
 
@@ -60,6 +61,10 @@ export function resetPerBoardCaches() {
  */
 export function applySnapshotToStores(snapshot: WorkspaceSnapshot, boardSince?: number) {
   useUserSettingsStore().hydrate(snapshot.userSettings ?? null)
+  // The signed-in user's tutorial progress MERGES rather than replaces (see the store): both id
+  // lists are grow-only sets, so a snapshot must never un-say a walkthrough this browser finished
+  // while the mirror write was failing. Absent ⇒ no server copy, and the local one stands.
+  useTutorialStore().mergeServerProgress(snapshot.tutorialProgress ?? null)
   useBoardStore().hydrate(snapshot.blocks, boardSince)
   useBoardStore().hydrateArchived(snapshot.archivedServices ?? [])
   usePipelinesStore().hydrate(

package/app/types/domain.ts

@@ -86,6 +86,9 @@ export type {
   UpdateWorkspaceSettingsInput,
   UserSettings,
   UpdateUserSettingsInput,
+  TutorialProgress,
+  UpdateTutorialProgressInput,
+  RecordTutorialEventInput,
   InfraSetup,
   InfraSetupStatus,
   InfraSetupArea,

package/app/types/reproduction.ts

@@ -0,0 +1,11 @@
+// Bugfix REPRODUCTION-PROOF shapes: the declared reproducing check as the executor-harness ran it
+// against the pre-fix tree and the final tree, and the verdict it computed from the two exit codes.
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+
+export type {
+  ReproductionProofMode,
+  ReproductionPhaseOutcome,
+  ReproductionReport,
+  ReproductionStatus,
+} from '@cat-factory/contracts'

package/app/utils/observability.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import type { PipelineStep, StepPhaseMetrics } from '~/types/execution'
-import { foldRunPhaseMetrics, totalInputTokens } from './observability'
+import { foldRunPhaseMetrics, formatCost, sumCosts, totalInputTokens } from './observability'
 
 describe('totalInputTokens', () => {
   it('sums all three input classes, so the headline matches Claude Code’s context gauge', () => {
@@ -85,3 +85,46 @@ describe('foldRunPhaseMetrics', () => {
     expect(row.calls).toBe(3)
   })
 })
+
+describe('formatCost', () => {
+  it('omits the figure entirely when nothing priced it', () => {
+    // Null, never "0.00": a deployment that cannot price a model and a step that cost nothing
+    // are opposite facts, and rendering both as zero states the wrong one confidently.
+    expect(formatCost(null, 'EUR')).toBeNull()
+    expect(formatCost(undefined, 'EUR')).toBeNull()
+    // A genuine zero still renders — it is a real, priced answer.
+    expect(formatCost(0, 'EUR')).toBe('0.00 EUR')
+  })
+
+  it('keeps more decimals under a unit, where most steps land', () => {
+    expect(formatCost(0.0037, 'EUR')).toBe('0.0037 EUR')
+    expect(formatCost(12.5, 'EUR')).toBe('12.50 EUR')
+  })
+
+  it('shows a threshold rather than rounding a real cost down to zero', () => {
+    // `0.0000` makes a priced-but-tiny step read as free — the same claim the null case is
+    // careful not to make. A cheap step is not a free one.
+    expect(formatCost(0.00001, 'EUR')).toBe('<0.0001 EUR')
+    expect(formatCost(0.0001, 'EUR')).toBe('0.0001 EUR')
+  })
+
+  it('labels the amount with the currency it was priced in rather than assuming one', () => {
+    // The price table's currency is operator-configured; the built-in one is EUR, not USD.
+    expect(formatCost(1, 'USD')).toBe('1.00 USD')
+    expect(formatCost(1)).toBe('1.00')
+  })
+})
+
+describe('sumCosts', () => {
+  it('adds the parts it can price', () => {
+    expect(sumCosts([1, 2, 0.5])).toBe(3.5)
+    expect(sumCosts([])).toBe(0)
+  })
+
+  it('declines to answer when any part is unpriced, rather than under-reporting', () => {
+    // A total that silently dropped its unpriceable term is a smaller number that still reads
+    // as complete — strictly worse than no number.
+    expect(sumCosts([1, null, 2])).toBeNull()
+    expect(sumCosts([undefined])).toBeNull()
+  })
+})

package/app/utils/observability.ts

@@ -36,6 +36,52 @@ export function totalInputTokens(m: {
   return m.promptTokens + (m.cacheReadTokens ?? 0) + (m.cacheWriteTokens ?? 0)
 }
 
+/**
+ * Smallest amount {@link formatCost} will print as a figure. Below it, four decimals round to
+ * `0.0000`, which is the same "free" claim a null renders as `0.00` — so such an amount is
+ * shown as a threshold instead.
+ */
+const MIN_RENDERED_COST = 0.0001
+
+/**
+ * Format an estimated cost for display, or null when there is nothing honest to show.
+ *
+ * Null in ⇒ null out, and the caller renders the tokens WITHOUT a money figure: a cost the
+ * deployment could not price and a cost of zero are different facts, and `0.00` claims the
+ * second one. Small amounts keep more decimals because most steps land well under a unit and
+ * rounding them all to `0.00` would make the whole column useless; an amount too small even
+ * for those decimals is rendered as `<0.0001` rather than rounded down to the zero this
+ * function exists to avoid printing.
+ */
+export function formatCost(amount: number | null | undefined, currency?: string): string | null {
+  if (amount == null) return null
+  const value = formatCostAmount(amount)
+  // The currency is a bare ISO code beside the number rather than a locale symbol: the amounts
+  // come from a deployment-configured table whose code is whatever an operator set, and a
+  // symbol we guessed for an unrecognised code would be a wrong label on a right number.
+  return currency ? `${value} ${currency}` : value
+}
+
+function formatCostAmount(amount: number): string {
+  if (amount > 0 && amount < MIN_RENDERED_COST) return `<${MIN_RENDERED_COST}`
+  // Four decimals under a unit, where most steps land; two above it, where they read as money.
+  return amount.toFixed(amount > 0 && amount < 1 ? 4 : 2)
+}
+
+/**
+ * Sum costs across rows the way the backend folds do: NULL contaminates rather than being
+ * skipped as zero, so a total that could not price one of its parts declines to answer instead
+ * of reporting a smaller number that reads as complete.
+ */
+export function sumCosts(values: readonly (number | null | undefined)[]): number | null {
+  let total = 0
+  for (const value of values) {
+    if (value == null) return null
+    total += value
+  }
+  return total
+}
+
 /** Compact duration: 850 → "850ms", 1500 → "1.5s", 90_000 → "1m 30s". */
 export function formatMs(ms: number): string {
   if (ms < 1000) return `${Math.round(ms)}ms`
@@ -78,6 +124,7 @@ const EMPTY_PHASE: Omit<StepPhaseMetrics, 'phase'> = {
   completionTokens: 0,
   carryCostTokens: 0,
   errors: 0,
+  costEstimate: 0,
 }
 
 /**
@@ -116,6 +163,9 @@ export function foldRunPhaseMetrics(steps: readonly PipelineStep[]): StepPhaseMe
         completionTokens: prev.completionTokens + row.completionTokens,
         carryCostTokens: prev.carryCostTokens + row.carryCostTokens,
         errors: prev.errors + row.errors,
+        // Same contaminating sum the backend fold uses: one unpriced phase makes the run's
+        // figure unknown rather than quietly smaller.
+        costEstimate: sumCosts([prev.costEstimate, row.costEstimate]),
       })
     }
   }