@cat-factory/app 0.213.1 → 0.215.0

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/binaryOutput.spec.ts

@@ -428,8 +428,9 @@ describe('binaryOutputPickIssues, generative half', () => {
     expect(pick.issues).toEqual([])
   })
 
-  // The FORMAT half, mirroring kernel's `binaryFormatCoverage` — and its three outcomes, which
-  // are what a second copy of the rule most easily loses.
+  // The FORMAT half. The rule itself is contracts' `binaryFormatCoverage`, tested there; what
+  // these pin is the picker's own job, which is mapping its three outcomes onto two issues that
+  // read differently: a refusal and an advisory.
   const meshy = {
     id: 'meshy',
     modalities: ['3d-model' as const],
@@ -490,6 +491,59 @@ describe('binaryOutputPickIssues, generative half', () => {
     expect(pick.uncoveredModalities).toEqual([])
   })
 
+  it('flags an OVERLAP as ADVISORY, where the content type stops deciding', () => {
+    // The step saves and starts: two producers of one content type is the reason the selection is
+    // a list. What it costs is a decision nobody wrote down, and this is the surface where the
+    // person who knows the answer has the step's prompt already open.
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['retro', 'flux'] },
+      catalog,
+      true,
+      [...generators, { id: 'flux', modalities: ['image' as const] }],
+    )
+    expect(pick.issues).toEqual(['generator_overlap'])
+    expect(pick.generatorOverlaps).toEqual([{ modality: 'image', generatorIds: ['retro', 'flux'] }])
+  })
+
+  it('reads a repeated id as ONE integration, exactly as the backend resolves it', () => {
+    // A step naming one integration twice holds one producer, so there is no choice to advise
+    // about, and the unknown-id list must not name the same missing id twice either.
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['retro', 'retro', 'ghost', 'ghost'] },
+      catalog,
+      true,
+      generators,
+    )
+    expect(pick.issues).toEqual(['unknown_generator'])
+    expect(pick.unknownGeneratorIds).toEqual(['ghost'])
+    expect(pick.generatorOverlaps).toEqual([])
+  })
+
+  it('says nothing about an overlap while one integration produces each content type', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['retro', 'studio'] },
+      catalog,
+      true,
+      generators,
+    )
+    expect(pick.issues).not.toContain('generator_overlap')
+    expect(pick.generatorOverlaps).toEqual([])
+  })
+
+  it('claims no overlap about a set nobody could read', () => {
+    // Same rule every other generative judgement here follows: an unreachable mothership answers
+    // the same empty list a deployment registering nothing does, and only one of them is a fact.
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['retro', 'flux'] },
+      catalog,
+      true,
+      [],
+      true,
+    )
+    expect(pick.issues).toEqual(['generators_unavailable'])
+    expect(pick.generatorOverlaps).toEqual([])
+  })
+
   it('still judges an EMPTY set, which is a real answer about the deployment', () => {
     // The distinction the flag exists for: same empty list, opposite fact, opposite message.
     const pick = binaryOutputPickIssues(

package/app/utils/binaryOutput.ts

@@ -1,5 +1,14 @@
-import { ASSET_STORAGE_CAPABILITY, normalizeMediaType } from '@cat-factory/contracts'
-import type { BinaryModality, RegisteredBinaryGenerator } from '@cat-factory/contracts'
+import {
+  ASSET_STORAGE_CAPABILITY,
+  binaryFormatCoverage,
+  binaryModalityOverlaps,
+  normalizeMediaType,
+} from '@cat-factory/contracts'
+import type {
+  BinaryModality,
+  BinaryModalityOverlap,
+  RegisteredBinaryGenerator,
+} from '@cat-factory/contracts'
 import type {
   BinaryOutputArtifact,
   BinaryOutputConfig,
@@ -412,6 +421,22 @@ export type BinaryOutputPickIssue =
    * comes to look exactly like "this is fine".
    */
   | 'media_type_unverifiable'
+  /**
+   * Two or more selected integrations produce the SAME content type, so the content type no
+   * longer decides which one the agent calls.
+   *
+   * ADVISORY, like `media_type_unverifiable` and unlike everything above it: the step saves, it
+   * starts, and selecting two producers of one kind is the whole reason the selection is a list.
+   * What it costs is a decision nobody has written down, and the agent resolves an unstated
+   * choice by picking one and picking it consistently, which is invisible in the artifacts,
+   * since every one of them has the right modality, the right format and a clean storage verdict.
+   *
+   * It is raised HERE as well as in the agent's brief because this is the surface where it can be
+   * acted on: the person selecting two integrations is the one who knows why, and the step's
+   * prompt is a field they already have open. The brief catches the step whose author did not
+   * think to write it; this catches the author.
+   */
+  | 'generator_overlap'
 
 /** What the builder found wrong with one step's selection, and which ids to name. */
 export interface BinaryOutputPickState {
@@ -426,6 +451,12 @@ export interface BinaryOutputPickState {
   uncoveredMediaTypes: readonly string[]
   /** The declared formats that could not be judged, kept apart from the refusal above. */
   unverifiableMediaTypes: readonly string[]
+  /**
+   * The content types more than one selected integration produces, with the ids that share each.
+   * Computed through the SAME `binaryModalityOverlaps` the agent's brief renders from, so the
+   * picker and the brief cannot describe one selection two ways.
+   */
+  generatorOverlaps: readonly BinaryModalityOverlap[]
 }
 
 /**
@@ -433,6 +464,12 @@ export interface BinaryOutputPickState {
  * `binaryGeneratorSelectionIssues` so the builder surfaces the `binary_output_generator_invalid`
  * refusal before the round trip rather than inventing a second opinion.
  *
+ * What is mirrored is the DISPOSITION: which conditions refuse, which advise, and what each is
+ * called on this surface. The two rules underneath are IMPORTED (`binaryFormatCoverage`,
+ * `binaryModalityOverlaps`), because a rule restated on both sides of a wire is one that can come
+ * to two answers about the same selection, and the reader here is the person who would then be
+ * told the builder's version and the agent the other.
+ *
  * `unavailable` is the one state that is NOT derivable from the list, which is why the snapshot
  * carries it as its own flag. An empty list normally IS a real empty — this deployment registers
  * none — and that is exactly why a selected id in that state is `unknown_generator` rather than
@@ -453,16 +490,21 @@ function generatorPickIssues(
   uncovered: BinaryModality[]
   uncoveredMediaTypes: string[]
   unverifiableMediaTypes: string[]
+  overlaps: BinaryModalityOverlap[]
 } {
   const none = {
     unknownGeneratorIds: [],
     uncovered: [],
     uncoveredMediaTypes: [],
     unverifiableMediaTypes: [],
+    overlaps: [],
   }
   if (unavailable) return { issues: ['generators_unavailable'], ...none }
   const byId = new Map(generators.map((g) => [g.id, g]))
-  const selectedIds = config?.generatorIds ?? []
+  // Deduplicated on the way in, exactly as `resolveBinaryGeneratorSelection` does it on the
+  // backend: a step that names one integration twice holds ONE, and every line below states a
+  // count or a list a repeat would double.
+  const selectedIds = [...new Set(config?.generatorIds ?? [])]
   const unknownGeneratorIds = selectedIds.filter((id) => !byId.has(id))
   // Coverage is judged against what RESOLVED, exactly as admission judges it: an unknown id
   // contributes no content types, so a step whose only audio generator is unregistered is told
@@ -470,49 +512,28 @@ function generatorPickIssues(
   const selected = selectedIds.flatMap((id) => byId.get(id) ?? [])
   const covered = new Set(selected.flatMap((g) => g.modalities))
   const uncovered = (config?.modalities ?? []).filter((m) => !covered.has(m))
-  const format = formatCoverage(config?.mediaTypes ?? [], selected)
+  const format = binaryFormatCoverage(config?.mediaTypes ?? [], selected)
+  // Judged against what RESOLVED, like every rule above it, and against the SELECTION rather than
+  // the step's declared content types: the case that most often puts two producers of one kind on
+  // one step is the one where neither is the deliverable (an image generated to feed a mesh API),
+  // and gating on `modalities` would go silent on exactly that step.
+  const overlaps = binaryModalityOverlaps(selected)
   const issues: BinaryOutputPickIssue[] = []
   if (unknownGeneratorIds.length) issues.push('unknown_generator')
   if (uncovered.length) issues.push('modality_uncovered')
   if (format.uncovered.length) issues.push('media_type_uncovered')
   if (format.unverifiable.length) issues.push('media_type_unverifiable')
+  if (overlaps.length) issues.push('generator_overlap')
   return {
     issues,
     unknownGeneratorIds,
     uncovered,
     uncoveredMediaTypes: format.uncovered,
     unverifiableMediaTypes: format.unverifiable,
+    overlaps,
   }
 }
 
-/**
- * The SPA's copy of kernel's `binaryFormatCoverage`, restated for the reason the two `*_service`
- * members above are: the builder cannot see kernel, and the wire vocabulary that does cross
- * (`@cat-factory/contracts`) carries the schema, not the rule.
- *
- * The THIRD outcome is what must not be lost in the copying. A generator that declares no formats
- * has said "only my modality is known" — a documented state, not an empty answer — so a
- * requirement it cannot be judged against is unverifiable and the step still starts. Collapsing
- * that into `uncovered` would flag steps the backend admits (and send someone editing a selection
- * that is fine); collapsing it into silence would present an unchecked requirement as a checked
- * one.
- */
-function formatCoverage(
-  required: readonly string[],
-  selected: readonly Pick<RegisteredBinaryGenerator, 'mediaTypes'>[],
-): { uncovered: string[]; unverifiable: string[] } {
-  const emitted = new Set(selected.flatMap((g) => g.mediaTypes ?? []))
-  const undeclared = selected.some((g) => (g.mediaTypes ?? []).length === 0)
-  const uncovered: string[] = []
-  const unverifiable: string[] = []
-  for (const mediaType of required) {
-    if (emitted.has(mediaType)) continue
-    if (undeclared) unverifiable.push(mediaType)
-    else uncovered.push(mediaType)
-  }
-  return { uncovered, unverifiable }
-}
-
 /**
  * Validate a step's selection against the workspace's RESOLVED catalog — the same catalog run
  * admission re-validates against, which is the whole reason the picker offers only resolved
@@ -572,6 +593,7 @@ export function binaryOutputPickIssues(
       uncoveredModalities: generative.uncovered,
       uncoveredMediaTypes: generative.uncoveredMediaTypes,
       unverifiableMediaTypes: generative.unverifiableMediaTypes,
+      generatorOverlaps: generative.overlaps,
     }
   }
 
@@ -595,5 +617,6 @@ export function binaryOutputPickIssues(
     uncoveredModalities: generative.uncovered,
     uncoveredMediaTypes: generative.uncoveredMediaTypes,
     unverifiableMediaTypes: generative.unverifiableMediaTypes,
+    generatorOverlaps: generative.overlaps,
   }
 }

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]),
       })
     }
   }

package/app/utils/reproduction.ts

@@ -0,0 +1,51 @@
+import type { ReproductionStatus } from '~/types/reproduction'
+
+// Presentation for the BUGFIX REPRODUCTION PROOF verdict.
+//
+// The lookup is by a wire value, so it lives here as an EXHAUSTIVE `Record` keyed off the
+// contracts union rather than as a t() call over a key assembled at the call site. The typed-key
+// check cannot see a runtime-assembled key, so a fourth verdict added to the union would ship as a
+// blank chip on exactly the surface whose job is to say what was and was not proven; keyed this
+// way it fails to compile until the copy exists.
+
+export interface ReproductionStatusPresentation {
+  /** Short chip copy: the verdict as one or two words. */
+  chip: string
+  /** One sentence a reviewer decides on. */
+  verdict: string
+  icon: string
+  /** Whether this verdict IS proof — the only one a collapsed row states completely. */
+  proven: boolean
+}
+
+export const REPRODUCTION_STATUS_KEYS: Record<ReproductionStatus, ReproductionStatusPresentation> =
+  {
+    reproduced: {
+      chip: 'panels.stepDetail.reproduction.status.reproduced',
+      verdict: 'panels.stepDetail.reproduction.verdict.reproduced',
+      icon: 'i-lucide-bug-off',
+      proven: true,
+    },
+    inconclusive: {
+      chip: 'panels.stepDetail.reproduction.status.inconclusive',
+      verdict: 'panels.stepDetail.reproduction.verdict.inconclusive',
+      icon: 'i-lucide-bug',
+      proven: false,
+    },
+    declared_infeasible: {
+      chip: 'panels.stepDetail.reproduction.status.declared_infeasible',
+      verdict: 'panels.stepDetail.reproduction.verdict.declared_infeasible',
+      icon: 'i-lucide-clipboard-list',
+      proven: false,
+    },
+  }
+
+/**
+ * The two checkouts the same command was run against. A literal pair rather than a lookup: it is
+ * the feature's own vocabulary (the tree BEFORE the change and the tree after it), not a wire
+ * union that can grow.
+ */
+export const REPRODUCTION_TREE_KEYS = {
+  base: 'panels.stepDetail.reproduction.tree.base',
+  final: 'panels.stepDetail.reproduction.tree.final',
+} as const