@cat-factory/app 0.302.2 → 0.303.0

package/app/components/panels/ResultWindowShell.vue

@@ -97,7 +97,7 @@ const props = withDefaults(
   }>(),
   {
     icon: 'i-lucide-square',
-    iconClass: 'bg-slate-500/15 text-slate-300',
+    iconClass: 'bg-app-500/15 text-toned',
     subtitle: undefined,
     width: '3xl',
     variant: 'stretch',
@@ -244,20 +244,20 @@ const binaryOutputSummary = computed(() => {
 const effortOpen = ref(false)
 const hint = computed(() => (effortReport.value ? effortHint(effortReport.value) : null))
 const CHIP_CLASS = {
-  easy: 'bg-emerald-500/15 text-emerald-300',
-  moderate: 'bg-amber-500/15 text-amber-300',
-  hard: 'bg-rose-500/15 text-rose-300',
+  easy: 'bg-app-success-500/15 text-app-success-300',
+  moderate: 'bg-app-warning-500/15 text-app-warning-300',
+  hard: 'bg-app-error-500/15 text-app-error-300',
 } as const
 const chipClass = computed(() =>
   effortReport.value ? CHIP_CLASS[effortBand(effortReport.value.difficulty)] : '',
 )
 
 const backdropClass = computed(() => [
-  'fixed inset-0 z-50 flex max-h-[100dvh] justify-center bg-slate-950/70 backdrop-blur-sm',
+  'fixed inset-0 z-50 flex max-h-[100dvh] justify-center bg-app-950/70 backdrop-blur-sm',
   props.variant === 'centered' ? 'items-center p-4' : 'items-stretch',
 ])
 const panelClass = computed(() => [
-  'flex w-full flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl',
+  'flex w-full flex-col overflow-hidden rounded-2xl border border-default bg-default shadow-2xl',
   RESULT_WINDOW_WIDTH_CLASS[props.width],
   props.variant === 'centered' ? 'max-h-[90dvh]' : 'm-4',
 ])
@@ -280,7 +280,7 @@ const panelClass = computed(() => [
         :aria-label="title"
         :data-testid="testid ?? 'result-window'"
       >
-        <header class="flex items-center gap-3 border-b border-slate-800 px-5 py-3">
+        <header class="flex items-center gap-3 border-b border-default px-5 py-3">
           <span
             class="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg"
             :class="iconClass"
@@ -288,8 +288,8 @@ const panelClass = computed(() => [
             <UIcon :name="icon" class="h-4 w-4" />
           </span>
           <div class="min-w-0 flex-1">
-            <h2 class="truncate text-sm font-semibold text-slate-100">{{ title }}</h2>
-            <p v-if="subtitle" class="truncate text-[11px] text-slate-400">{{ subtitle }}</p>
+            <h2 class="truncate text-sm font-semibold text-app-100">{{ title }}</h2>
+            <p v-if="subtitle" class="truncate text-[11px] text-muted">{{ subtitle }}</p>
           </div>
           <!-- Window-specific header content (status badges, counts). -->
           <slot name="header-extras" />
@@ -300,7 +300,7 @@ const panelClass = computed(() => [
             @restarted="requestClose"
           />
           <button
-            class="rounded-md p-1.5 text-slate-400 hover:bg-slate-800 hover:text-slate-200"
+            class="rounded-md p-1.5 text-muted hover:bg-elevated hover:text-default"
             data-testid="result-window-close"
             :aria-label="t('common.close')"
             @click="requestClose"
@@ -318,18 +318,18 @@ const panelClass = computed(() => [
              so it can't crowd a window out; expands in place. -->
         <section
           v-if="effortReport"
-          class="shrink-0 border-t border-slate-800 bg-slate-900/60"
+          class="shrink-0 border-t border-default bg-default/60"
           data-testid="result-window-effort"
         >
           <button
             type="button"
-            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-slate-800/40"
+            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-elevated/40"
             :aria-expanded="effortOpen"
             data-testid="result-window-effort-toggle"
             @click="effortOpen = !effortOpen"
           >
-            <UIcon name="i-lucide-gauge" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
-            <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            <UIcon name="i-lucide-gauge" class="h-3.5 w-3.5 shrink-0 text-muted" />
+            <span class="text-[11px] font-semibold uppercase tracking-wide text-muted">
               {{ t('panels.stepDetail.effort.heading') }}
             </span>
             <span
@@ -338,12 +338,12 @@ const panelClass = computed(() => [
             >
               {{ t('panels.stepDetail.effort.outOfTen', { value: effortReport.difficulty }) }}
             </span>
-            <span v-if="hint" class="min-w-0 flex-1 truncate text-[12px] text-slate-400">
+            <span v-if="hint" class="min-w-0 flex-1 truncate text-[12px] text-muted">
               {{ hint }}
             </span>
             <UIcon
               :name="effortOpen ? 'i-lucide-chevron-down' : 'i-lucide-chevron-up'"
-              class="ms-auto h-3.5 w-3.5 shrink-0 text-slate-500"
+              class="ms-auto h-3.5 w-3.5 shrink-0 text-dimmed"
             />
           </button>
           <div v-if="effortOpen" class="max-h-56 overflow-y-auto px-5 pb-3">
@@ -356,12 +356,12 @@ const panelClass = computed(() => [
              red — a failed checkout is the one an operator opened the window to read. -->
         <section
           v-if="validationReport"
-          class="shrink-0 border-t border-slate-800 bg-slate-900/60"
+          class="shrink-0 border-t border-default bg-default/60"
           data-testid="result-window-validation"
         >
           <button
             type="button"
-            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-slate-800/40"
+            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-elevated/40"
             :aria-expanded="validationOpen"
             data-testid="result-window-validation-toggle"
             @click="validationOpen = !validationOpen"
@@ -369,17 +369,17 @@ const panelClass = computed(() => [
             <UIcon
               :name="validationReport.passed ? 'i-lucide-shield-check' : 'i-lucide-shield-alert'"
               class="h-3.5 w-3.5 shrink-0"
-              :class="validationReport.passed ? 'text-emerald-400' : 'text-rose-400'"
+              :class="validationReport.passed ? 'text-app-success-400' : 'text-app-error-400'"
             />
-            <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            <span class="text-[11px] font-semibold uppercase tracking-wide text-muted">
               {{ t('panels.stepDetail.validation.heading') }}
             </span>
             <span
               class="shrink-0 rounded px-1.5 py-0.5 text-[11px] font-medium tabular-nums"
               :class="
                 validationReport.passed
-                  ? 'bg-emerald-500/15 text-emerald-300'
-                  : 'bg-rose-500/15 text-rose-300'
+                  ? 'bg-app-success-500/15 text-app-success-300'
+                  : 'bg-app-error-500/15 text-app-error-300'
               "
             >
               {{
@@ -388,7 +388,7 @@ const panelClass = computed(() => [
                   : t('panels.stepDetail.validation.failed')
               }}
             </span>
-            <span class="min-w-0 flex-1 truncate text-[12px] text-slate-400">
+            <span class="min-w-0 flex-1 truncate text-[12px] text-muted">
               {{
                 t('panels.stepDetail.validation.attempts', {
                   attempts: validationReport.attempts,
@@ -398,7 +398,7 @@ const panelClass = computed(() => [
             </span>
             <UIcon
               :name="validationOpen ? 'i-lucide-chevron-down' : 'i-lucide-chevron-up'"
-              class="ms-auto h-3.5 w-3.5 shrink-0 text-slate-500"
+              class="ms-auto h-3.5 w-3.5 shrink-0 text-dimmed"
             />
           </button>
           <div v-if="validationOpen" class="max-h-72 overflow-y-auto px-5 pb-3">
@@ -412,12 +412,12 @@ const panelClass = computed(() => [
              opened the window to read. -->
         <section
           v-if="reproductionReport"
-          class="shrink-0 border-t border-slate-800 bg-slate-900/60"
+          class="shrink-0 border-t border-default bg-default/60"
           data-testid="result-window-reproduction"
         >
           <button
             type="button"
-            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-slate-800/40"
+            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-elevated/40"
             :aria-expanded="reproductionOpen"
             data-testid="result-window-reproduction-toggle"
             @click="reproductionOpen = !reproductionOpen"
@@ -425,27 +425,27 @@ const panelClass = computed(() => [
             <UIcon
               :name="reproductionKeys!.icon"
               class="h-3.5 w-3.5 shrink-0"
-              :class="reproductionKeys!.proven ? 'text-emerald-400' : 'text-amber-400'"
+              :class="reproductionKeys!.proven ? 'text-app-success-400' : 'text-app-warning-400'"
             />
-            <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            <span class="text-[11px] font-semibold uppercase tracking-wide text-muted">
               {{ t('panels.stepDetail.reproduction.heading') }}
             </span>
             <span
               class="shrink-0 rounded px-1.5 py-0.5 text-[11px] font-medium"
               :class="
                 reproductionKeys!.proven
-                  ? 'bg-emerald-500/15 text-emerald-300'
-                  : 'bg-amber-500/15 text-amber-300'
+                  ? 'bg-app-success-500/15 text-app-success-300'
+                  : 'bg-app-warning-500/15 text-app-warning-300'
               "
             >
               {{ t(reproductionKeys!.chip) }}
             </span>
-            <span class="min-w-0 flex-1 truncate text-[12px] text-slate-400">
+            <span class="min-w-0 flex-1 truncate text-[12px] text-muted">
               {{ t(reproductionKeys!.verdict) }}
             </span>
             <UIcon
               :name="reproductionOpen ? 'i-lucide-chevron-down' : 'i-lucide-chevron-up'"
-              class="ms-auto h-3.5 w-3.5 shrink-0 text-slate-500"
+              class="ms-auto h-3.5 w-3.5 shrink-0 text-dimmed"
             />
           </button>
           <div v-if="reproductionOpen" class="max-h-72 overflow-y-auto px-5 pb-3">
@@ -460,26 +460,26 @@ const panelClass = computed(() => [
              not all read as. -->
         <section
           v-if="binaryOutputs"
-          class="shrink-0 border-t border-slate-800 bg-slate-900/60"
+          class="shrink-0 border-t border-default bg-default/60"
           data-testid="result-window-binary-outputs"
         >
           <button
             type="button"
-            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-slate-800/40"
+            class="flex w-full items-center gap-2 px-5 py-2 text-start hover:bg-elevated/40"
             :aria-expanded="binaryOutputsOpen"
             data-testid="result-window-binary-outputs-toggle"
             @click="binaryOutputsOpen = !binaryOutputsOpen"
           >
-            <UIcon name="i-lucide-image" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
-            <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            <UIcon name="i-lucide-image" class="h-3.5 w-3.5 shrink-0 text-muted" />
+            <span class="text-[11px] font-semibold uppercase tracking-wide text-muted">
               {{ t('binaryOutput.heading') }}
             </span>
-            <span class="min-w-0 flex-1 truncate text-[12px] text-slate-400">
+            <span class="min-w-0 flex-1 truncate text-[12px] text-muted">
               {{ binaryOutputSummary }}
             </span>
             <UIcon
               :name="binaryOutputsOpen ? 'i-lucide-chevron-down' : 'i-lucide-chevron-up'"
-              class="ms-auto h-3.5 w-3.5 shrink-0 text-slate-500"
+              class="ms-auto h-3.5 w-3.5 shrink-0 text-dimmed"
             />
           </button>
           <div v-if="binaryOutputsOpen && activeStep" class="max-h-72 overflow-y-auto px-5 pb-3">

package/app/components/panels/RunDetailLoadState.vue

@@ -25,8 +25,8 @@ const error = computed(() => execution.fullError(props.instanceId))
 <template>
   <div
     v-if="loading || error"
-    class="flex items-center gap-2 border-b border-slate-800 px-4 py-2 text-[11px]"
-    :class="error ? 'text-rose-300' : 'text-slate-400'"
+    class="flex items-center gap-2 border-b border-default px-4 py-2 text-[11px]"
+    :class="error ? 'text-app-error-300' : 'text-muted'"
     data-testid="run-detail-load-state"
   >
     <UIcon

package/app/components/panels/StepContainerStatus.vue

@@ -51,22 +51,22 @@ const CONTAINER_STATUS_META: Record<
   starting: {
     icon: 'i-lucide-loader-circle',
     spin: true,
-    cls: 'border-sky-900/50 bg-sky-950/30 text-sky-300',
+    cls: 'border-app-info-900/50 bg-app-info-950/30 text-app-info-300',
   },
   up: {
     icon: 'i-lucide-box',
     spin: false,
-    cls: 'border-emerald-900/50 bg-emerald-950/30 text-emerald-300',
+    cls: 'border-app-success-900/50 bg-app-success-950/30 text-app-success-300',
   },
   errored: {
     icon: 'i-lucide-circle-x',
     spin: false,
-    cls: 'border-rose-900/50 bg-rose-950/30 text-rose-300',
+    cls: 'border-app-error-900/50 bg-app-error-950/30 text-app-error-300',
   },
   destroyed: {
     icon: 'i-lucide-power-off',
     spin: false,
-    cls: 'border-slate-800 bg-slate-900/40 text-slate-400',
+    cls: 'border-default bg-default/40 text-muted',
   },
 }
 
@@ -105,16 +105,16 @@ const { copy: copyText } = useCopyToClipboard()
         />
         <span class="font-medium">{{ t(CONTAINER_STATUS_KEYS[containerStatus]) }}</span>
         <template v-if="phaseLabel && containerStatus === 'up'">
-          <span class="text-slate-500">·</span>
+          <span class="text-dimmed">·</span>
           <span>{{ phaseLabel }}</span>
         </template>
       </div>
       <dl v-if="step.container?.id || step.container?.url" class="mt-2 space-y-1">
         <div v-if="step.container?.id" class="flex items-center gap-2">
-          <dt class="shrink-0 text-[11px] uppercase tracking-wide text-slate-500">
+          <dt class="shrink-0 text-[11px] uppercase tracking-wide text-dimmed">
             {{ t('panels.stepMeta.container.id') }}
           </dt>
-          <dd class="truncate font-mono text-[11px] text-slate-300" :title="step.container.id">
+          <dd class="truncate font-mono text-[11px] text-toned" :title="step.container.id">
             {{ step.container.id }}
           </dd>
           <UButton
@@ -129,10 +129,10 @@ const { copy: copyText } = useCopyToClipboard()
           />
         </div>
         <div v-if="step.container?.url" class="flex items-center gap-2">
-          <dt class="shrink-0 text-[11px] uppercase tracking-wide text-slate-500">
+          <dt class="shrink-0 text-[11px] uppercase tracking-wide text-dimmed">
             {{ t('panels.stepMeta.container.url') }}
           </dt>
-          <dd class="truncate font-mono text-[11px] text-slate-300">
+          <dd class="truncate font-mono text-[11px] text-toned">
             <a
               :href="step.container.url"
               target="_blank"

package/app/components/panels/StepDelegatedStatus.logic.spec.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest'
+import {
+  DELEGATION_STATUS_KEY,
+  DELEGATION_STATUS_META,
+  KNOWN_DELEGATION_STATUSES,
+  UNKNOWN_DELEGATION_STATUS_META,
+  delegatedUsageUnreported,
+  delegationStatusView,
+  externalRunHref,
+} from './StepDelegatedStatus.logic'
+import type { RunDelegationStatus } from '~/types/execution'
+
+/**
+ * The status of external work is a CLOSED, PERSISTED vocabulary, which is the pairing that makes an
+ * exhaustive `Record` over it total against the TYPE and partial against the DATA. These pin the
+ * two ways that regresses: a member with no presentation, and a stored value this build does not
+ * know taking the whole panel down with it.
+ */
+describe('delegation status presentation', () => {
+  it('gives every status in the wire vocabulary its own row in both maps', () => {
+    // Derived from the schema the backend decides against, not from a list retyped here.
+    expect(Object.keys(DELEGATION_STATUS_META).sort()).toEqual(
+      [...KNOWN_DELEGATION_STATUSES].sort(),
+    )
+    expect(Object.keys(DELEGATION_STATUS_KEY).sort()).toEqual([...KNOWN_DELEGATION_STATUSES].sort())
+  })
+
+  it('never points two statuses at one label', () => {
+    const keys = Object.values(DELEGATION_STATUS_KEY)
+    expect(new Set(keys).size).toBe(keys.length)
+  })
+
+  it('resolves a known status to its own row', () => {
+    const view = delegationStatusView('running')
+    expect(view.status).toBe('running')
+    expect(view.meta).toEqual(DELEGATION_STATUS_META.running)
+    expect(view.labelKey).toBe(DELEGATION_STATUS_KEY.running)
+  })
+
+  it('renders a status this build does not know as unrecognised, NAMING the raw value', () => {
+    // The panel is the only place a person can read what happened to work the platform cannot see,
+    // so a bare `Record` lookup here is `undefined.cls` thrown during render: a white screen over
+    // the answer. Guessing onto a current member is the other wrong answer, because nothing can
+    // know which one was meant and the wrong guess reports the wrong outcome for a live run.
+    const view = delegationStatusView('quiesced')
+    expect(view.status).toBeNull()
+    expect(view.meta).toEqual(UNKNOWN_DELEGATION_STATUS_META)
+    expect(view.labelKey).toBe('panels.stepMeta.delegated.status.unrecognised')
+    expect(view.labelParams).toEqual({ status: 'quiesced' })
+  })
+
+  it('does not mistake an inherited object member for a status', () => {
+    // `DELEGATION_STATUS_META` is an ordinary object literal, so a persisted value naming
+    // `constructor` or `toString` reads back as a truthy non-key on a plain truthiness check.
+    for (const value of ['constructor', 'toString', 'hasOwnProperty']) {
+      expect(delegationStatusView(value).status).toBeNull()
+    }
+  })
+
+  it('treats an absent status as unrecognised rather than throwing', () => {
+    expect(delegationStatusView(undefined).status).toBeNull()
+  })
+})
+
+describe('externalRunHref', () => {
+  it('links an ordinary run url', () => {
+    expect(externalRunHref('https://github.com/acme/widgets/actions/runs/99')).toBe(
+      'https://github.com/acme/widgets/actions/runs/99',
+    )
+    // http too: a deployment's own internal CI is reachable, and this is a link a person clicks,
+    // not a request the platform makes.
+    expect(externalRunHref('http://ci.internal/jobs/12')).toBe('http://ci.internal/jobs/12')
+  })
+
+  it('refuses a scheme that would EXECUTE in this origin', () => {
+    // The value comes from an external system's API and lands in the card's primary affordance.
+    // Bound straight into `href`, these run as script in the SPA's own origin when clicked.
+    for (const url of ['javascript:alert(1)', 'JavaScript:alert(1)', 'data:text/html,<script>']) {
+      expect(externalRunHref(url)).toBeNull()
+    }
+  })
+
+  it('refuses what it cannot parse, and says nothing about a record with no url', () => {
+    expect(externalRunHref('/relative/path')).toBeNull()
+    expect(externalRunHref('')).toBeNull()
+    expect(externalRunHref(null)).toBeNull()
+    expect(externalRunHref(undefined)).toBeNull()
+  })
+})
+
+describe('delegatedUsageUnreported', () => {
+  // The two surfaces answering this question have to agree: the backend's reporting-gap fold
+  // counts the same settled steps into `delegatedStepsWithoutUsage`, and a card keyed on the
+  // executor's DECLARATION disagreed with it in both directions at once.
+  const step = (
+    status: RunDelegationStatus,
+    metrics?: { calls: number },
+  ): Parameters<typeof delegatedUsageUnreported>[0] =>
+    ({
+      delegated: {
+        executor: 'acme:executor',
+        status,
+        correlationKey: 'k',
+        poll: null,
+        attempts: [{ startedAt: 0 }],
+      },
+      ...(metrics ? { metrics } : {}),
+    }) as Parameters<typeof delegatedUsageUnreported>[0]
+
+  it('warns on a SETTLED step that reported nothing, whatever the executor declared', () => {
+    expect(delegatedUsageUnreported(step('done'), { telemetry: 'self-reported' })).toBe(true)
+    expect(delegatedUsageUnreported(step('failed'), { telemetry: 'not-reported' })).toBe(true)
+  })
+
+  it('stays silent beside a real number, even from an executor that declared none', () => {
+    expect(
+      delegatedUsageUnreported(step('done', { calls: 4 }), { telemetry: 'not-reported' }),
+    ).toBe(false)
+  })
+
+  it('warns while work is IN FLIGHT only where the declaration says none is coming', () => {
+    // A `self-reported` executor files with its result, so it has correctly reported nothing yet
+    // and the card must not claim a permanent gap while a person watches the step.
+    expect(delegatedUsageUnreported(step('running'), { telemetry: 'self-reported' })).toBe(false)
+    expect(delegatedUsageUnreported(step('running'), { telemetry: 'not-reported' })).toBe(true)
+    // An executor this build no longer registers: nothing here can say otherwise.
+    expect(delegatedUsageUnreported(step('starting'), undefined)).toBe(true)
+  })
+
+  it('says nothing at all about a step that dispatched nowhere external', () => {
+    expect(
+      delegatedUsageUnreported({} as Parameters<typeof delegatedUsageUnreported>[0], undefined),
+    ).toBe(false)
+  })
+})

package/app/components/panels/StepDelegatedStatus.logic.ts

@@ -0,0 +1,160 @@
+import {
+  delegatedSpendUnreported,
+  isRunDelegationStatus,
+  runDelegationStatusSchema,
+} from '@cat-factory/contracts'
+import type { PipelineStep, RunDelegationStatus } from '~/types/execution'
+
+// The DELEGATION status vocabulary's presentation. Kept out of the SFC on the same seam as
+// `StepToolServers.logic.ts`, so the rule can be asserted without mounting a component.
+//
+// The rule: the status of external work is a CLOSED and PERSISTED vocabulary, so a row written by
+// another build can hold a member this one retired. Every `Record<RunDelegationStatus, …>` over it
+// is therefore total against the TYPE and partial against the DATA, and indexing one bare is
+// `undefined.cls` thrown during render: a white screen over the one panel that says what happened
+// to work the platform cannot see. A value this build does not know is RENDERED as unrecognised,
+// carrying the raw string, never guessed onto a current member: nothing can know which one was
+// meant, and the wrong guess reports the wrong outcome for a run somebody may need to go and stop.
+
+/** How each status renders. Exhaustive, so a member added to the vocabulary fails to compile here. */
+export const DELEGATION_STATUS_META: Record<
+  RunDelegationStatus,
+  { icon: string; spin: boolean; cls: string }
+> = {
+  starting: {
+    icon: 'i-lucide-loader-circle',
+    spin: true,
+    cls: 'border-app-info-900/50 bg-app-info-950/30 text-app-info-300',
+  },
+  running: {
+    icon: 'i-lucide-radio',
+    spin: false,
+    cls: 'border-primary/50 bg-primary/10 text-primary',
+  },
+  done: {
+    icon: 'i-lucide-circle-check',
+    spin: false,
+    cls: 'border-app-success-900/50 bg-app-success-950/30 text-app-success-300',
+  },
+  failed: {
+    icon: 'i-lucide-circle-x',
+    spin: false,
+    cls: 'border-app-error-900/50 bg-app-error-950/30 text-app-error-300',
+  },
+  cancelled: {
+    icon: 'i-lucide-circle-slash',
+    spin: false,
+    cls: 'border-app-warning-900/50 bg-app-warning-950/30 text-app-warning-300',
+  },
+}
+
+/**
+ * Static literal keys (not a runtime-built `t(`…${status}`)`) so the typed-message-keys check
+ * covers them; exhaustive on the same vocabulary and for the same reason as
+ * {@link DELEGATION_STATUS_META}.
+ */
+export const DELEGATION_STATUS_KEY: Record<RunDelegationStatus, string> = {
+  starting: 'panels.stepMeta.delegated.status.starting',
+  running: 'panels.stepMeta.delegated.status.running',
+  done: 'panels.stepMeta.delegated.status.done',
+  failed: 'panels.stepMeta.delegated.status.failed',
+  cancelled: 'panels.stepMeta.delegated.status.cancelled',
+}
+
+/**
+ * How a status this build does not recognise renders: the WARNING tone, like `cancelled`, because
+ * both mean "something here wants a person to look". Its own row rather than a borrowed one, so
+ * nothing reads it as one of the known outcomes.
+ */
+export const UNKNOWN_DELEGATION_STATUS_META = {
+  icon: 'i-lucide-circle-help',
+  spin: false,
+  cls: 'border-app-warning-900/50 bg-app-warning-950/30 text-app-warning-300',
+}
+
+/** The vocabulary as the SCHEMA states it: what a parity assertion grades the two maps against. */
+export const KNOWN_DELEGATION_STATUSES = runDelegationStatusSchema.options
+
+/** What the card renders for one persisted status, known or not. */
+export interface DelegationStatusView {
+  /** The narrowed member, or null for a value this build does not know. */
+  status: RunDelegationStatus | null
+  meta: { icon: string; spin: boolean; cls: string }
+  /** The i18n key plus the parameters it takes; the raw value rides the unrecognised one. */
+  labelKey: string
+  labelParams: Record<string, string>
+}
+
+/**
+ * Resolve one persisted status into everything the card shows for it.
+ *
+ * One function rather than three guarded lookups in the template, because the guard is the whole
+ * point: three places to narrow is three places to forget, and forgetting once throws.
+ */
+export function delegationStatusView(status: string | undefined): DelegationStatusView {
+  if (status && isRunDelegationStatus(status)) {
+    return {
+      status,
+      meta: DELEGATION_STATUS_META[status],
+      labelKey: DELEGATION_STATUS_KEY[status],
+      labelParams: {},
+    }
+  }
+  return {
+    status: null,
+    meta: UNKNOWN_DELEGATION_STATUS_META,
+    labelKey: 'panels.stepMeta.delegated.status.unrecognised',
+    labelParams: { status: status ?? '' },
+  }
+}
+
+/**
+ * The run URL as an `href`, or null when it is not one this SPA may link to.
+ *
+ * Everything on the delegation record comes from an EXTERNAL system: `url` is whatever that
+ * system's API answered with, and this card puts it in the primary affordance a person clicks.
+ * Bound straight into `href`, a `javascript:` value executes in the SPA's own origin, which is the
+ * same boundary `resolveExternalToolUrl` draws for a resolver-supplied URL and the same one
+ * kernel's `hostMarkdown.link` draws server-side.
+ *
+ * A refused value is not dropped: the caller renders it as plain text, because "the executor
+ * reported this link and we will not follow it" is a fact worth showing, and a silently missing
+ * link reads as a run that reported none.
+ */
+export function externalRunHref(url: string | null | undefined): string | null {
+  if (!url) return null
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? url : null
+  } catch {
+    // A relative or malformed value: not something to link to, and not an error either. The card
+    // shows the raw string, which is what the executor actually said.
+    return null
+  }
+}
+
+/**
+ * Whether the card says the platform is not measuring this step's spend.
+ *
+ * Two questions, and the split is the whole point. Once the work has SETTLED the answer is
+ * contracts' `delegatedSpendUnreported`, over what actually LANDED, which is the same rule the
+ * backend's reporting-gap fold reads: keying this side on the executor's declared `telemetry`
+ * instead made the two disagree in both directions at once, an executor declaring `self-reported`
+ * that files nothing showing no warning here while the debug overview counted the step, and one
+ * declaring `not-reported` that does fill `DelegationResult.usage` printing "not reported" beside
+ * a real number.
+ *
+ * While the work is IN FLIGHT only the declaration can say anything, because a `self-reported`
+ * executor files with its result and has correctly reported nothing yet. So the line is shown for
+ * one that declares the number is never coming, and for one this build no longer registers, where
+ * nothing here can say otherwise.
+ */
+export function delegatedUsageUnreported(
+  step: Pick<PipelineStep, 'delegated' | 'metrics'>,
+  executor: { telemetry?: 'not-reported' | 'self-reported' } | undefined,
+): boolean {
+  if (delegatedSpendUnreported(step)) return true
+  const status = step.delegated?.status
+  const inFlight = status === 'starting' || status === 'running'
+  return inFlight && executor?.telemetry !== 'self-reported'
+}