@cat-factory/app 0.217.2 → 0.219.0

package/app/components/settings/RiskPolicyPanel.vue

@@ -5,7 +5,13 @@
 // task inspector's "Merge policy" dropdown selects from. Exactly one preset is the
 // default; it cannot be deleted or un-defaulted (the backend enforces this too).
 import { computed, reactive, ref, watch } from 'vue'
-import type { MergeClassRules, RiskPolicy, RequirementConcernLevel } from '~/types/merge'
+import type {
+  ClassRulesByRole,
+  DryRunRoles,
+  MergeClassRules,
+  RiskPolicy,
+  RequirementConcernLevel,
+} from '~/types/merge'
 import type { StepGating } from '@cat-factory/contracts'
 import {
   RISK_POLICY_AXES,
@@ -13,6 +19,7 @@ import {
   type RiskPolicyAxis,
 } from '~/utils/riskPolicy'
 import MergeClassRulesEditor from '~/components/settings/MergeClassRulesEditor.vue'
+import MergeRolePolicyEditor from '~/components/settings/MergeRolePolicyEditor.vue'
 
 const { t } = useI18n()
 
@@ -78,6 +85,11 @@ interface Draft {
   // Per-change-class auto-merge rules. An OMITTED class means "use the score ceilings above",
   // so `{}` is the identity — the editor stores `thresholds` as an omission for that reason.
   classRules: MergeClassRules
+  // The ROLE layer over those rules: per-role narrowing (narrow-only, so `{}` is the identity)
+  // and the roles whose runs are sandboxed. Both replace the stored value wholesale on save,
+  // which is why clearing one in the editor is a plain omission.
+  classRulesByRole: ClassRulesByRole
+  dryRunRoles: DryRunRoles
   // Implementation-fork decision gating (edited 0..100, stored 0..1); disabled ⇒ off in `auto`.
   forkEnabled: boolean
   forkMinComplexity: number
@@ -115,6 +127,8 @@ function toDraft(p: RiskPolicy): Draft {
     maxRequirementConcernAllowed: p.maxRequirementConcernAllowed,
     autoMergeEnabled: p.autoMergeEnabled,
     classRules: { ...p.classRules },
+    classRulesByRole: { ...p.classRulesByRole },
+    dryRunRoles: [...p.dryRunRoles],
     forkEnabled: p.forkDecision?.enabled ?? false,
     forkMinComplexity: Math.round((p.forkDecision?.minComplexity ?? 0.5) * 100),
     forkMinRisk: Math.round((p.forkDecision?.minRisk ?? 0.4) * 100),
@@ -158,6 +172,8 @@ async function save(p: RiskPolicy) {
       maxRequirementConcernAllowed: d.maxRequirementConcernAllowed,
       autoMergeEnabled: d.autoMergeEnabled,
       classRules: d.classRules,
+      classRulesByRole: d.classRulesByRole,
+      dryRunRoles: d.dryRunRoles,
       forkDecision: forkGating(d),
     })
     toast.add({
@@ -213,7 +229,12 @@ const draft = reactive<Draft>({
   maxRequirementIterations: 6,
   maxRequirementConcernAllowed: 'none',
   autoMergeEnabled: true,
+  // The create row authors the numbers only. Class and role rules start at their identity and
+  // are edited on the saved preset, where each rule can be shown beside the base rule (and the
+  // track record) it narrows — neither reads as anything on a policy that does not exist yet.
   classRules: {},
+  classRulesByRole: {},
+  dryRunRoles: [],
   forkEnabled: false,
   forkMinComplexity: 50,
   forkMinRisk: 40,
@@ -367,6 +388,19 @@ async function create() {
         />
       </div>
 
+      <!-- The role layer over those rules: what a run may do depending on WHO started it, up to
+           and including a full sandbox. Directly under the base rules it narrows, since a role
+           rule is only readable against the rule it applies to. -->
+      <div class="mt-3 rounded-md border border-slate-800 bg-slate-900/40 p-3">
+        <MergeRolePolicyEditor
+          v-model:class-rules-by-role="drafts[p.id]!.classRulesByRole"
+          v-model:dry-run-roles="drafts[p.id]!.dryRunRoles"
+          :class-rules="drafts[p.id]!.classRules"
+          :auto-merge-enabled="drafts[p.id]!.autoMergeEnabled"
+          :disabled="busy === p.id"
+        />
+      </div>
+
       <!-- Implementation-fork decision gate: propose materially different approaches before the
            Coder writes code (in `auto` tri-state, gated on the task estimate). -->
       <div class="mt-3 rounded-md border border-slate-800 bg-slate-900/40 p-3">

package/app/composables/useRunStart.spec.ts

@@ -0,0 +1,204 @@
+import { describe, expect, it, vi } from 'vitest'
+import { nextTick, ref, type Ref } from 'vue'
+import type { Block, Pipeline } from '~/types/domain'
+import type { RiskPolicy, WorkspaceRole } from '~/types/merge'
+import { useBoardStore } from '~/stores/board'
+import { useExecutionStore } from '~/stores/execution'
+import { useRiskPoliciesStore } from '~/stores/riskPolicies'
+import { useUiModeStore } from '~/stores/uiMode'
+import { useDryRunPolicy, useRunStart } from '~/composables/useRunStart'
+
+// `useRunStart` resolves the mode a start will run in from two independent facts: what the user
+// asked for, and whether the task's merge preset sandboxes their role. The stores are real (a
+// fresh Pinia per test); only the caller's resolved RBAC role and the store's start command are
+// stubbed, since neither an HTTP call nor an auth gate is what these assertions are about.
+const pipeline = { id: 'pl_build', name: 'Build' } as Pipeline
+
+const preset = (over: Partial<RiskPolicy> = {}): RiskPolicy =>
+  ({
+    id: 'mp_balanced',
+    name: 'Balanced',
+    maxComplexity: 0.6,
+    maxRisk: 0.4,
+    maxImpact: 0.5,
+    ciMaxAttempts: 10,
+    maxRequirementIterations: 6,
+    maxRequirementConcernAllowed: 'none',
+    maxTesterQualityIterations: 3,
+    releaseWatchWindowMinutes: 30,
+    releaseMaxAttempts: 1,
+    humanReviewGraceMinutes: 10,
+    judgeMinScore: 0.7,
+    judgeMaxBounces: 2,
+    autoMergeEnabled: true,
+    classRules: {},
+    classRulesByRole: {},
+    dryRunRoles: [],
+    isDefault: true,
+    createdAt: 0,
+    ...over,
+  }) as RiskPolicy
+
+/**
+ * Seed a board governed by `policy`, signed in as `role`, and hand back the composable.
+ *
+ * `b1` is the task under test. `b2` is a second one carrying its own preset, so a test can move
+ * the id the composable is bound to: that is what the inspector does, being mounted once for the
+ * session and following the board selection rather than being rebuilt per block.
+ */
+function setup(options: {
+  role: WorkspaceRole | null
+  policy?: RiskPolicy
+  otherPolicy?: RiskPolicy
+  advanced?: boolean
+}) {
+  const start = vi.fn().mockResolvedValue(true)
+  vi.stubGlobal('useWorkspaceAccess', () => ({ role: { value: options.role } }))
+  useBoardStore().blocks = [
+    { id: 'b1', level: 'task', title: 'Task' } as Block,
+    { id: 'b2', level: 'task', title: 'Other task', riskPolicyId: 'mp_other' } as Block,
+  ]
+  const other = options.otherPolicy ?? preset({ id: 'mp_other', isDefault: false })
+  useRiskPoliciesStore().hydrate([options.policy ?? preset(), other])
+  useUiModeStore().setMode(options.advanced === false ? 'basic' : 'advanced')
+  useExecutionStore().start = start
+  const blockId: Ref<string | undefined> = ref('b1')
+  return { run: useRunStart(blockId), start, blockId }
+}
+
+describe('useRunStart', () => {
+  it('starts live by default, sending no mode at all', async () => {
+    const { run, start } = setup({ role: 'member' })
+    expect(run.dryRun.value).toBe(false)
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b1', pipeline, { mode: undefined })
+  })
+
+  it('sends the request when the initiator asks for a sandbox', async () => {
+    const { run, start } = setup({ role: 'member' })
+    run.setRequested(true)
+    expect(run.dryRun.value).toBe(true)
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b1', pipeline, { mode: 'dry_run' })
+  })
+
+  it('clears the request once it has been spent, so the next run is live again', async () => {
+    const { run } = setup({ role: 'member' })
+    run.setRequested(true)
+    await run.start(pipeline)
+    expect(run.requested.value).toBe(false)
+  })
+
+  it('reports a policy sandbox and offers nothing to ask for', () => {
+    const { run } = setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    expect(run.forced.value).toBe(true)
+    expect(run.dryRun.value).toBe(true)
+    expect(run.canRequest.value).toBe(false)
+  })
+
+  // The engine reads the preset itself and reports the sandbox as policy rather than as a
+  // request, which is what lets the run explain a sandbox its initiator never chose. Re-sending
+  // it from here would file it under "they asked for this".
+  it('sends no mode for a policy sandbox: the engine settles that, not the caller', async () => {
+    const { run, start } = setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b1', pipeline, { mode: undefined })
+  })
+
+  it('leaves a role the preset does not list alone', () => {
+    const { run } = setup({ role: 'admin', policy: preset({ dryRunRoles: ['member'] }) })
+    expect(run.forced.value).toBe(false)
+    expect(run.canRequest.value).toBe(true)
+  })
+
+  // Auth-disabled dev resolves no role, so no entry can match. Reading absence as a tier would
+  // sandbox every run on a deployment that runs with auth off.
+  it('never force-sandboxes a caller with no resolved role', () => {
+    const { run } = setup({
+      role: null,
+      policy: preset({ dryRunRoles: ['admin', 'member', 'viewer'] }),
+    })
+    expect(run.forced.value).toBe(false)
+  })
+
+  // The request is an override of the default a basic-tier user would otherwise have got, and
+  // hiding it leaves exactly that default. A policy sandbox is not an override, so it is not
+  // subject to the tier at all.
+  it('offers the request only on the advanced tier, and states a sandbox on both', () => {
+    expect(setup({ role: 'member', advanced: false }).run.canRequest.value).toBe(false)
+    const basicForced = setup({
+      role: 'member',
+      advanced: false,
+      policy: preset({ dryRunRoles: ['member'] }),
+    })
+    expect(basicForced.run.forced.value).toBe(true)
+    expect(basicForced.run.dryRun.value).toBe(true)
+  })
+
+  it('falls back to the workspace default preset for a task that picks none', () => {
+    const { run } = setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    expect(run.preset.value?.id).toBe('mp_balanced')
+    expect(run.forced.value).toBe(true)
+  })
+
+  // The request belongs to the block it was made on, and the surface holding it outlives that
+  // block: the inspector is mounted once and follows the board selection. Carrying the request
+  // across would sandbox the NEXT run started, on a task nobody armed it for, with the Run
+  // button's icon the only tell and reading as a property of the task now shown.
+  it('drops a pending request when the block changes under it', async () => {
+    const { run, blockId, start } = setup({ role: 'member' })
+    run.setRequested(true)
+    expect(run.dryRun.value).toBe(true)
+
+    blockId.value = 'b2'
+    await nextTick()
+
+    expect(run.requested.value).toBe(false)
+    expect(run.dryRun.value).toBe(false)
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b2', pipeline, { mode: undefined })
+  })
+
+  // The other half of following the selection: the policy read is per BLOCK, so moving to a task
+  // governed by a sandboxing preset must report the sandbox rather than the previous task's.
+  it('re-reads the policy for the block it is now bound to', async () => {
+    const { run, blockId } = setup({
+      role: 'member',
+      otherPolicy: preset({ id: 'mp_other', isDefault: false, dryRunRoles: ['member'] }),
+    })
+    expect(run.forced.value).toBe(false)
+
+    blockId.value = 'b2'
+    await nextTick()
+
+    expect(run.forced.value).toBe(true)
+    expect(run.canRequest.value).toBe(false)
+  })
+})
+
+// The board's one-tap start and its drag-drop start resolve a task at the moment of the action
+// and have no block to bind a composable to, so they read the policy through the same functions
+// `useRunStart` wraps. Sharing them is what keeps a sandbox from being visible on one start
+// surface and silent on another.
+describe('useDryRunPolicy', () => {
+  it('answers per block, for a target resolved at the moment of the start', () => {
+    setup({
+      role: 'member',
+      otherPolicy: preset({ id: 'mp_other', isDefault: false, dryRunRoles: ['member'] }),
+    })
+    const { forcedFor, presetFor } = useDryRunPolicy()
+    expect(forcedFor('b1')).toBe(false)
+    expect(forcedFor('b2')).toBe(true)
+    expect(presetFor('b2')?.id).toBe('mp_other')
+  })
+
+  // A block with no preset of its own is governed by the workspace default, and so is one the
+  // board cannot resolve: the same fallback the engine makes, rather than reading an unresolved
+  // block as unsandboxed, which would state the safer-looking answer without knowing it.
+  it('falls back to the workspace default for a block carrying no preset', () => {
+    setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    const { forcedFor } = useDryRunPolicy()
+    expect(forcedFor('b1')).toBe(true)
+    expect(forcedFor(undefined)).toBe(true)
+  })
+})

package/app/composables/useRunStart.ts

@@ -0,0 +1,112 @@
+import { computed, ref, toValue, watch, type MaybeRefOrGetter } from 'vue'
+import { dryRunForcedForRole, type RunMode } from '@cat-factory/contracts'
+import type { Pipeline, RiskPolicy } from '~/types/domain'
+import { useBoardStore } from '~/stores/board'
+import { useExecutionStore } from '~/stores/execution'
+import { useRiskPoliciesStore } from '~/stores/riskPolicies'
+import { useUiModeStore } from '~/stores/uiMode'
+
+/**
+ * Whether this deployment's merge policy sandboxes the signed-in user's runs on a given block:
+ * the pipeline works and opens its pull request, and nothing merges.
+ *
+ * Exposed as FUNCTIONS of a block id rather than as computeds over one, because the start
+ * surfaces ask the question in two shapes and both must get the same answer. A control bound to
+ * a block (the inspector's Run menu, the focus view's picker) asks about that block and re-asks
+ * when the selection moves; the board's drop handler resolves its target at the moment of the
+ * drop and has no block to bind to. {@link useRunStart} wraps these for the first shape.
+ *
+ * `dryRunForcedForRole` is the contracts rule the engine applies at admission, not a restated
+ * `includes`: reading the role's absence (auth-disabled dev, where the SPA resolves no role) is
+ * the part that has to agree, since guessing a tier there would sandbox a whole deployment.
+ */
+export function useDryRunPolicy() {
+  const board = useBoardStore()
+  const riskPolicies = useRiskPoliciesStore()
+  const access = useWorkspaceAccess()
+
+  /**
+   * The preset that governs this task's merge decision: its own, else the workspace default
+   * (the same resolution the engine makes, via the store).
+   */
+  function presetFor(blockId: string | undefined): RiskPolicy | null {
+    return riskPolicies.resolve(board.getBlock(blockId ?? '')?.riskPolicyId)
+  }
+
+  /** That preset sandboxes runs started by the signed-in user's role, whatever they ask for. */
+  function forcedFor(blockId: string | undefined): boolean {
+    return dryRunForcedForRole(presetFor(blockId)?.dryRunRoles, access.role.value)
+  }
+
+  return { presetFor, forcedFor }
+}
+
+/**
+ * The run-mode half of starting a run, shared by every surface that offers a pipeline to start
+ * (the inspector's Run menu, the focus view's picker) so the three facts below cannot drift into
+ * two answers on two surfaces.
+ *
+ * A run is either live or a SANDBOX (`dry_run`): the pipeline works and opens its pull request,
+ * and nothing merges, at either exit. Two things can put it there, and they are not the same
+ * thing to a person reading the control:
+ *
+ *  - **A request.** The initiator asked for a sandbox on this run. An override of the default,
+ *    unset until asked for and never persisted, so it is `advanced`-tier: hiding it leaves
+ *    exactly the live run a basic-tier user would otherwise have started.
+ *  - **The task's merge preset.** It sandboxes the roles it lists (`dryRunRoles`), and a run
+ *    cannot ask its way out of that, which is the whole point of the setting. So it is stated
+ *    in BOTH tiers, and it REPLACES the request control rather than sitting beside it: a toggle
+ *    over a decision already made would be the concealed-setting failure in reverse.
+ */
+export function useRunStart(blockId: MaybeRefOrGetter<string | undefined>) {
+  const execution = useExecutionStore()
+  const uiMode = useUiModeStore()
+  const policy = useDryRunPolicy()
+
+  /** The caller's own explicit ask for THIS block. */
+  const requested = ref(false)
+
+  const preset = computed(() => policy.presetFor(toValue(blockId)))
+
+  /** This preset sandboxes runs started by the signed-in user's role, whatever they ask for. */
+  const forced = computed(() => policy.forcedFor(toValue(blockId)))
+
+  /** Whether to offer the request control at all: nothing to ask for once policy decided it. */
+  const canRequest = computed(() => uiMode.isAdvanced && !forced.value)
+
+  /** What the run WILL be, for a control that describes the start it is about to make. */
+  const dryRun = computed(() => forced.value || requested.value)
+
+  // The request belongs to the block it was made on, and the surfaces holding it OUTLIVE that
+  // block: the inspector is mounted once for the whole session and follows the board selection.
+  // Without this, arming a sandbox on one task and then selecting another silently sandboxes the
+  // next run started, on a task nobody asked it for. The button's icon is the only tell, and it
+  // reads as a property of the task now shown.
+  watch(
+    () => toValue(blockId),
+    () => {
+      requested.value = false
+    },
+  )
+
+  function setRequested(value: boolean) {
+    requested.value = value
+  }
+
+  /**
+   * Start `pipeline` on this block. Only an EXPLICIT request travels: a forced sandbox is the
+   * server's own reading of the preset, and re-sending it as a request would file the run's mode
+   * under "the initiator asked for this" when they did not, costing the run the advisory that
+   * explains a sandbox nobody chose.
+   */
+  async function start(pipeline: Pipeline): Promise<boolean> {
+    const id = toValue(blockId)
+    if (!id) return false
+    const mode: RunMode | undefined = requested.value ? 'dry_run' : undefined
+    const started = await execution.start(id, pipeline, { mode })
+    if (started) requested.value = false
+    return started
+  }
+
+  return { preset, forced, canRequest, dryRun, requested, setRequested, start }
+}

package/app/stores/execution/commands.ts

@@ -1,6 +1,6 @@
 import type { Ref } from 'vue'
 import type { ExecutionInstance, Pipeline } from '~/types/domain'
-import type { RequestStepChangesInput } from '@cat-factory/contracts'
+import type { RequestStepChangesInput, RunMode } from '@cat-factory/contracts'
 import type { IterationCapChoice } from '~/types/execution'
 import type { ReviewEffort } from '~/types/merge'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -36,8 +36,17 @@ export function createExecutionCommands(ctx: ExecutionCommandContext) {
    * pinned to an individual-usage model (Claude) needs the initiator's personal
    * password — supplied transparently from the local cache, and prompted via the
    * credential modal (then retried) when the server replies 428.
+   *
+   * `mode: 'dry_run'` REQUESTS a sandboxed run: the pipeline works and opens its pull request,
+   * and nothing merges. It is a request, not a decision — the task's merge preset can sandbox a
+   * role's runs whatever they asked for, so what the run got is read back off the run's own
+   * `mode`, never assumed from what was sent here.
    */
-  async function start(blockId: string, pipeline: Pipeline): Promise<boolean> {
+  async function start(
+    blockId: string,
+    pipeline: Pipeline,
+    options?: { mode?: RunMode },
+  ): Promise<boolean> {
     const ws = useWorkspaceStore()
     const personal = usePersonalSubscriptionsStore()
     // Returns false when the user cancels the personal-password prompt OR the start was
@@ -45,7 +54,15 @@ export function createExecutionCommands(ctx: ExecutionCommandContext) {
     // caller can revert its "Starting…" state without its own error handling.
     try {
       return await personal.withCredential(async (password) => {
-        await api.startExecution(ws.requireId(), blockId, { pipelineId: pipeline.id }, password)
+        await api.startExecution(
+          ws.requireId(),
+          blockId,
+          // Omitted rather than `mode: 'live'` for an ordinary start: `live` is what the absent
+          // field already means, and asking for it explicitly would read as a request to opt OUT
+          // of a policy sandbox, which is not something a start may do.
+          { pipelineId: pipeline.id, ...(options?.mode ? { mode: options.mode } : {}) },
+          password,
+        )
         await ws.refresh()
       })
     } catch (e) {

package/app/types/execution.ts

@@ -36,6 +36,7 @@ export type {
   PlatformAlertSettings,
   PlatformAlertThresholdOverrides,
   PlatformAlertWindow,
+  PlatformFailureKindRule,
   PlatformFailingRun,
   ReportWindow,
   ReportSpendDimension,

package/app/types/merge.ts

@@ -11,6 +11,12 @@ export type {
   MergeClassRollup,
   MergeClassRule,
   MergeClassRules,
+  RuleableChangeClass,
+  // The ROLE layer of a preset: per-role narrowing of the rules above, and the roles whose
+  // runs are sandboxed (they open a pull request and merge nothing).
+  ClassRulesByRole,
+  DryRunRoles,
+  WorkspaceRole,
   MergeTrackRecord,
   ReviewEffort,
   RequirementConcernLevel,

package/app/utils/failureKinds.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import type { PlatformFailureKindRule } from '~/types/execution'
+import {
+  AGENT_FAILURE_KINDS,
+  FAILURE_KIND_KEYS,
+  failureKindRuleFaults,
+  hasFailureKindRuleFaults,
+  isAgentFailureKind,
+  MAX_FAILURE_KIND_RULES,
+} from '~/utils/failureKinds'
+
+describe('the failure-kind vocabulary', () => {
+  it('offers exactly the kinds the contract declares, and labels every one', () => {
+    // The map is what both the dashboard breakdown and the alert-rule picker read, so a kind
+    // added to the contract without a label here would render a raw code in both.
+    expect(AGENT_FAILURE_KINDS.length).toBeGreaterThan(0)
+    for (const kind of AGENT_FAILURE_KINDS) expect(FAILURE_KIND_KEYS[kind]).toBeTruthy()
+    expect(Object.keys(FAILURE_KIND_KEYS).sort()).toEqual([...AGENT_FAILURE_KINDS].sort())
+  })
+
+  it('recognises a current kind and refuses a retired or mistyped one', () => {
+    // Re-exported from `@cat-factory/contracts` rather than reimplemented, because the backend
+    // asks the identical question of an operator-typed kind in the env var. Pinned through the
+    // SPA's own import path so the re-export cannot quietly disappear.
+    expect(isAgentFailureKind('evicted')).toBe(true)
+    // The case the predicate exists for: a kind that a release retired still arrives on stored
+    // rules and old run rows, and must render as itself rather than as `undefined` or as
+    // whichever current member a guess landed on.
+    expect(isAgentFailureKind('evicetd')).toBe(false)
+  })
+
+  it('never offers more kinds than a rule list may hold, so the cap cannot bind first', () => {
+    // What makes "one rule per kind" the binding limit in the editor, and therefore what lets
+    // the add button simply stop rather than seeding a row the contract would refuse.
+    expect(AGENT_FAILURE_KINDS.length).toBeLessThanOrEqual(MAX_FAILURE_KIND_RULES)
+  })
+})
+
+describe('failureKindRuleFaults', () => {
+  const rule = (over: Partial<PlatformFailureKindRule> = {}): PlatformFailureKindRule => ({
+    kind: 'evicted',
+    maxShare: 0.05,
+    ...over,
+  })
+
+  it('accepts a well-formed set of rules', () => {
+    expect(
+      failureKindRuleFaults([rule(), rule({ kind: 'timeout', maxShare: 1, minCount: 3 })]),
+    ).toEqual({ rows: [], tooMany: false })
+    expect(failureKindRuleFaults([])).toEqual({ rows: [], tooMany: false })
+    expect(hasFailureKindRuleFaults(failureKindRuleFaults([rule()]))).toBe(false)
+  })
+
+  it('names the 1-based rows the backend would refuse', () => {
+    // The share bounds mirror the contract: 0 is satisfied by any distribution (including a kind
+    // that never occurred), and there is nothing above "all of them".
+    expect(failureKindRuleFaults([rule({ maxShare: 0 })]).rows).toEqual([1])
+    expect(failureKindRuleFaults([rule({ maxShare: 1.5 })]).rows).toEqual([1])
+    expect(failureKindRuleFaults([rule(), rule({ kind: 'timeout', minCount: 0 })]).rows).toEqual([
+      2,
+    ])
+    expect(failureKindRuleFaults([rule({ kind: 'timeout', minCount: 2.5 })]).rows).toEqual([1])
+  })
+
+  it('names BOTH rows of a duplicated kind, since either could be the one to fix', () => {
+    expect(failureKindRuleFaults([rule(), rule({ maxShare: 0.5 })]).rows).toEqual([1, 2])
+  })
+
+  it('reports an over-long list as its own fault, not as a bad row', () => {
+    // "There are too many rules" is fixed by deleting any of them, so pointing at a row number
+    // would name a row that is perfectly well-formed. The two faults travel separately for that
+    // reason, and either one alone must still stop the save.
+    const many = Array.from({ length: MAX_FAILURE_KIND_RULES + 1 }, (_, i) =>
+      rule({ kind: `kind${i}` }),
+    )
+    const faults = failureKindRuleFaults(many)
+    expect(faults).toEqual({ rows: [], tooMany: true })
+    expect(hasFailureKindRuleFaults(faults)).toBe(true)
+    // Exactly at the cap is fine — the bound is inclusive, as `v.maxLength` is.
+    expect(failureKindRuleFaults(many.slice(0, MAX_FAILURE_KIND_RULES)).tooMany).toBe(false)
+  })
+})

package/app/utils/failureKinds.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// Shared presentation for the run FAILURE TAXONOMY — the vocabulary the operator dashboard
+// renders as a breakdown and the alert settings panel offers as the subject of a per-kind
+// rule. Two surfaces answering about the same set, so the enum→key map lives here once: a
+// second copy is a map that drifts, and the surface that drifts is the one where an operator
+// picks the kind a page is wired to.
+//
+// The map is an exhaustive `Record<AgentFailureKind, …>`, so adding a kind to the contract
+// fails the typecheck here rather than rendering a raw code in either place.
+//
+// What is PRESENTATION lives here; what is a RULE comes from `@cat-factory/contracts` and is
+// re-exported so a component has one import. `isAgentFailureKind` in particular is not the
+// SPA's to own: the backend asks the identical question of an operator-typed kind in
+// `PLATFORM_ALERTS_FAILURE_KIND_RATES`, and two copies of "which kinds exist" is the pair that
+// drifts the moment one is retired.
+// ---------------------------------------------------------------------------
+
+import { agentFailureKindSchema, MAX_FAILURE_KIND_RULES } from '@cat-factory/contracts'
+import type { AgentFailureKind, PlatformFailureKindRule } from '~/types/execution'
+
+export { isAgentFailureKind, MAX_FAILURE_KIND_RULES } from '@cat-factory/contracts'
+
+/** i18n key per failure kind. */
+export const FAILURE_KIND_KEYS: Record<AgentFailureKind, string> = {
+  preflight: 'platformObservability.failureKind.preflight',
+  dispatch: 'platformObservability.failureKind.dispatch',
+  environment: 'platformObservability.failureKind.environment',
+  evicted: 'platformObservability.failureKind.evicted',
+  timeout: 'platformObservability.failureKind.timeout',
+  agent: 'platformObservability.failureKind.agent',
+  job_failed: 'platformObservability.failureKind.job_failed',
+  rejected: 'platformObservability.failureKind.rejected',
+  companion_rejected: 'platformObservability.failureKind.companion_rejected',
+  stalled: 'platformObservability.failureKind.stalled',
+  cancelled: 'platformObservability.failureKind.cancelled',
+  unknown: 'platformObservability.failureKind.unknown',
+}
+
+/**
+ * The kinds a human may be OFFERED, in the contract's own declared order.
+ *
+ * Read off the picklist rather than restated, so the choices a rule can be written against are
+ * the choices the backend recognises. The DISPLAYED set is deliberately not the same thing as
+ * the set of values that may ARRIVE: a stored rule or a persisted run row can still name a kind
+ * a later release retired, which `isAgentFailureKind` is for.
+ */
+export const AGENT_FAILURE_KINDS = agentFailureKindSchema.options as readonly AgentFailureKind[]
+
+/**
+ * Whether a stored per-kind rule list would be REFUSED by the contract, and why.
+ *
+ * One implementation shared by the editor and the save path, because they are the same question
+ * asked twice: a fault the editor flags but the save path does not is a save that fails on the
+ * WHOLE settings blob, for a reason the sheet never showed and about a sibling setting the admin
+ * never touched.
+ *
+ * The two faults are kept APART rather than folded into one list of bad rows, because they need
+ * different fixes and one of them belongs to no row in particular: "row 3 is malformed" is fixed
+ * in row 3, while "there are more rules than the contract allows" is fixed by deleting any of
+ * them. Reporting the second as a row number would point at a row that is perfectly fine.
+ *
+ * Deliberately mirrors the contract rather than re-deciding anything: a share in (0, 1], a whole
+ * minimum count of 1 or more when one is set, at most one rule per kind, and at most
+ * {@link MAX_FAILURE_KIND_RULES} rules.
+ */
+export interface FailureKindRuleFaults {
+  /** 1-based positions of individual rules the contract would refuse. */
+  rows: number[]
+  /** Whether the LIST is over the contract's cap, which is no single row's fault. */
+  tooMany: boolean
+}
+
+export function failureKindRuleFaults(
+  rules: readonly PlatformFailureKindRule[],
+): FailureKindRuleFaults {
+  const counts = new Map<string, number>()
+  for (const rule of rules) counts.set(rule.kind, (counts.get(rule.kind) ?? 0) + 1)
+  const rows = rules.flatMap((rule, index) => {
+    const shareOk = rule.maxShare > 0 && rule.maxShare <= 1
+    const countOk =
+      rule.minCount === undefined || (Number.isInteger(rule.minCount) && rule.minCount >= 1)
+    const unique = (counts.get(rule.kind) ?? 0) === 1
+    return shareOk && countOk && unique ? [] : [index + 1]
+  })
+  return { rows, tooMany: rules.length > MAX_FAILURE_KIND_RULES }
+}
+
+/** Whether a list is savable at all — the one question both call sites actually branch on. */
+export function hasFailureKindRuleFaults(faults: FailureKindRuleFaults): boolean {
+  return faults.rows.length > 0 || faults.tooMany
+}