@cat-factory/app 0.313.0 → 0.315.1

package/app/modular/nav-contributions.ts

@@ -196,6 +196,7 @@ export interface NavCommandSpec {
  * dead button. Consumer modules don't use these — they carry their own `run`.
  */
 export const NAV_ACTIONS = [
+  'describeWork',
   'assistant',
   'guidedReview',
   'buildPipeline',
@@ -346,6 +347,26 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  * the whole sidebar costs it nothing it is there to do.
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
+  {
+    // The one-sentence intake (issue #2258): what needs doing, a service, feature or bug. First in
+    // Create, because filing a task is the most frequent thing anyone creates, and until now it had
+    // no entry here at all (it lived on each frame). Every tier and the intake role: describing
+    // work is what that role is for.
+    id: 'describe-work',
+    labelKey: 'queue.describeWork',
+    icon: 'i-lucide-plus',
+    surfaces: S('sidebar', 'command'),
+    gate: (g) => g.canWriteBoard && g.boardHasService,
+    action: 'describeWork',
+    intake: true,
+    testId: 'nav-describe-work',
+    sidebar: { group: 'create', order: 1 },
+    command: {
+      group: 'create',
+      order: 1,
+      keywordsKey: 'layout.commandBar.keywords.describeWork',
+    },
+  },
   {
     // The in-app assistant. `intake: true` and not `advanced`, because it is the shortest route
     // to the two things a narrowed role is on the board to do (put a repository on it, file a

package/app/pages/index.vue

@@ -164,6 +164,7 @@ const TutorialNudge = defineAsyncView(() => import('~/components/tutorial/Tutori
 const RolePrompt = defineAsyncView(() => import('~/components/layout/RolePrompt.vue'))
 // The queue: the board's second view (issue #2258), loaded the first time someone opens it.
 const QueueView = defineAsyncView(() => import('~/components/queue/QueueView.vue'))
+const DescribeWorkModal = defineAsyncView(() => import('~/components/queue/DescribeWorkModal.vue'))
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -532,6 +533,7 @@ watch(
         <AddTaskModal />
         <ReviewFrictionDialog v-if="ui.reviewFrictionContext" />
         <CreateInitiativeModal />
+        <DescribeWorkModal v-if="ui.describeWorkOpen" />
         <CommandBar />
         <PersonalCredentialModal />
         <ConfirmDialog />

package/app/stores/publicApiKeys.spec.ts

@@ -9,6 +9,7 @@ function key(over: Partial<PublicApiKey> = {}): PublicApiKey {
     id: 'pak_1',
     accountId: 'acc1',
     workspaceId: 'ws1',
+    workspaceIds: ['ws1'],
     label: 'CI',
     scope: 'write',
     createdByUserId: null,
@@ -110,6 +111,33 @@ describe('publicApiKeys store', () => {
     expect(body).toHaveBeenCalledWith({ label: 'mine', scope: 'write', actsAsSelf: true })
   })
 
+  it('sends a reach only when one was chosen, so the default stays this workspace alone', async () => {
+    // An omitted `workspaceIds` and a `null` one mean opposite things on the wire (this board vs
+    // every board in the account), so the store must never turn "not chosen" into a value.
+    const body = vi.fn((_body: unknown) => Promise.resolve({ key: key(), secret: 's' }))
+    vi.stubGlobal('useApi', () => ({ createPublicApiKey: (_ws: string, b: unknown) => body(b) }))
+
+    const store = usePublicApiKeysStore()
+    await store.create('ci', 'read')
+    expect(body).toHaveBeenLastCalledWith({ label: 'ci', scope: 'read', actsAsSelf: false })
+
+    await store.create('all', 'read', false, null)
+    expect(body).toHaveBeenLastCalledWith({
+      label: 'all',
+      scope: 'read',
+      actsAsSelf: false,
+      workspaceIds: null,
+    })
+
+    await store.create('two', 'read', false, ['ws1', 'ws2'])
+    expect(body).toHaveBeenLastCalledWith({
+      label: 'two',
+      scope: 'read',
+      actsAsSelf: false,
+      workspaceIds: ['ws1', 'ws2'],
+    })
+  })
+
   it('revoke drops the key from the list', async () => {
     vi.stubGlobal('useApi', () => ({
       listPublicApiKeys: () => Promise.resolve({ keys: [key({ id: 'a' }), key({ id: 'b' })] }),

package/app/stores/publicApiKeys.ts

@@ -58,17 +58,31 @@ export const usePublicApiKeysStore = defineStore('publicApiKeys', () => {
    * `actsAsSelf` binds the key to the signed-in user's PERSONAL subscriptions, so a headless run
    * it starts can unlock them with the password sent on that call. Passed through rather than
    * defaulted here: the server writes the id off the session, so this is only ever a yes/no.
+   *
+   * `workspaceIds` is the key's reach: omitted for this workspace alone, `null` for every workspace
+   * in the account, or a list. Anything past this workspace needs an account admin.
    */
   async function create(
     label: string,
     scope: PublicApiScope,
     actsAsSelf = false,
+    workspaceIds?: string[] | null,
   ): Promise<CreatedPublicApiKey> {
     const ws = useWorkspaceStore()
-    const created = await api.createPublicApiKey(ws.requireId(), { label, scope, actsAsSelf })
+    const workspaceId = ws.requireId()
+    const created = await api.createPublicApiKey(workspaceId, {
+      label,
+      scope,
+      actsAsSelf,
+      ...(workspaceIds === undefined ? {} : { workspaceIds }),
+    })
     // Prepend: the backend lists newest-first, so the freshly minted key belongs at the
-    // top — matching the order a subsequent `load()` would produce.
-    keys.value = [created.key, ...keys.value]
+    // top — matching the order a subsequent `load()` would produce. A key picked to reach only
+    // other workspaces is not in this board's list, and revoking it from here would be refused as
+    // a no-op, so it is not shown.
+    const reaches =
+      created.key.workspaceIds === null || created.key.workspaceIds.includes(workspaceId)
+    if (reaches) keys.value = [created.key, ...keys.value]
     available.value = true
     return created
   }

package/app/stores/ui/modals.ts

@@ -27,6 +27,14 @@ export interface AddTaskPrefill {
   description?: string
   /** Context items staged on the new task (e.g. the source issue), linked once created. */
   context?: PendingContext[]
+  /**
+   * Choices a person already made on another surface (the one-sentence intake), carried over so
+   * the hand-off does not quietly reset them. Absent means the form's own defaults.
+   */
+  taskType?: 'feature' | 'bug'
+  pipelineId?: string
+  riskPolicyId?: string
+  modelPresetId?: string
 }
 
 /**
@@ -90,6 +98,11 @@ export interface ReviewFrictionModalContext {
    * started a second pipeline run against the same request.
    */
   pending?: () => boolean
+  /**
+   * Close the form that raised the friction. "Go review" and each debt row leave for a waiting
+   * task, and the form must not stay open over it; only the opener knows which form it is.
+   */
+  onLeave: () => void
 }
 
 /** Clears both hub came-from markers; injected into the slices whose `open*` handlers reset them. */
@@ -340,6 +353,17 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   function closeStartFromDesign() {
     startFromDesign.value = null
   }
+  // The one-sentence intake ("Describe new work", issue #2258): open, and the service it opened
+  // on, or null to let the reader pick one. The full form above stays the home of every other kind.
+  const describeWorkOpen = ref(false)
+  const describeWorkServiceId = ref<string | null>(null)
+  function openDescribeWork(serviceId: string | null = null) {
+    describeWorkServiceId.value = serviceId
+    describeWorkOpen.value = true
+  }
+  function closeDescribeWork() {
+    describeWorkOpen.value = false
+  }
   function openAddTask(containerId: string, prefill: AddTaskPrefill | null = null) {
     addTaskPrefill.value = prefill
     addTaskContainerId.value = containerId
@@ -405,6 +429,10 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     closeStartFromDesign,
     openAddTask,
     closeAddTask,
+    describeWorkOpen,
+    describeWorkServiceId,
+    openDescribeWork,
+    closeDescribeWork,
     openReviewFriction,
     closeReviewFriction,
     openAddRecurring,

package/app/utils/describeWork.spec.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { DERIVED_TITLE_MAX, splitDescribedWork } from '~/utils/describeWork'
+
+describe('splitDescribedWork', () => {
+  it('uses one short sentence as the title and adds no description', () => {
+    expect(splitDescribedWork('  Fix the login redirect  ')).toEqual({
+      title: 'Fix the login redirect',
+    })
+  })
+
+  it('titles with the first sentence and keeps the WHOLE text as the description', () => {
+    const text = 'Add an audit log. Record each sign-in with the time and the user.'
+    expect(splitDescribedWork(text)).toEqual({ title: 'Add an audit log', description: text })
+  })
+
+  it('reads only the first line for the title', () => {
+    const text = 'Rate limit per API key\nUse a token bucket. 100 requests a minute.'
+    expect(splitDescribedWork(text)).toEqual({ title: 'Rate limit per API key', description: text })
+  })
+
+  it('shortens a long first sentence at a word boundary, with an ellipsis', () => {
+    const words = 'word '.repeat(40).trim()
+    const { title, description } = splitDescribedWork(words)
+    expect(title.length).toBeLessThanOrEqual(DERIVED_TITLE_MAX)
+    expect(title.endsWith('word…')).toBe(true)
+    expect(description).toBe(words)
+  })
+
+  it('does not cut a dotted name such as a file or a version', () => {
+    expect(splitDescribedWork('Bump vite to 7.1 in package.json').title).toBe(
+      'Bump vite to 7.1 in package.json',
+    )
+  })
+
+  it('does not end a sentence at a common abbreviation', () => {
+    const text = 'Fix e.g. the login redirect loop. It happens on Safari.'
+    expect(splitDescribedWork(text)).toEqual({
+      title: 'Fix e.g. the login redirect loop',
+      description: text,
+    })
+    expect(splitDescribedWork('Ask Dr. Smith about the export. She owns it.').title).toBe(
+      'Ask Dr. Smith about the export',
+    )
+  })
+
+  it('treats a run of dots as one mark', () => {
+    expect(splitDescribedWork('Fix this... later, after the release.').title).toBe('Fix this')
+    expect(splitDescribedWork('Use a cache, e.g. Redis, for sessions.').title).toBe(
+      'Use a cache, e.g. Redis, for sessions',
+    )
+  })
+
+  it('ends a sentence at a full-width mark, with or without a space after it', () => {
+    const text = '修复登录重定向。记录每次登录。'
+    expect(splitDescribedWork(text)).toEqual({ title: '修复登录重定向', description: text })
+  })
+
+  it('keeps a question or an exclamation mark, and drops a period', () => {
+    expect(splitDescribedWork('Why does login fail?')).toEqual({ title: 'Why does login fail?' })
+    // A final period says nothing the title does not, so it adds no description.
+    expect(splitDescribedWork('Fix the login redirect.')).toEqual({
+      title: 'Fix the login redirect',
+    })
+  })
+
+  it('never cuts an emoji in half when it shortens', () => {
+    const text = `${'a'.repeat(DERIVED_TITLE_MAX - 2)}😀😀😀 more words after it`
+    const { title } = splitDescribedWork(text)
+    expect(title).not.toMatch(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/)
+    expect(Array.from(title).length).toBeLessThanOrEqual(DERIVED_TITLE_MAX)
+  })
+
+  it('returns an empty title for blank input, so the dialog cannot submit it', () => {
+    expect(splitDescribedWork('   \n ')).toEqual({ title: '' })
+  })
+})

package/app/utils/describeWork.ts

@@ -0,0 +1,71 @@
+/** The longest title the one-box intake derives. Long enough for a sentence, short for a card. */
+export const DERIVED_TITLE_MAX = 80
+
+/**
+ * Abbreviations whose period does not end a sentence. Only the common ones a task description
+ * starts with: the title is derived, so a miss costs a short title, never lost text (the whole text
+ * is the description).
+ */
+const ABBREVIATIONS = new Set(['e.g', 'i.e', 'etc', 'vs', 'cf', 'dr', 'mr', 'mrs', 'ms', 'st'])
+
+/** Ends a sentence. Full-width marks end one with or without a following space. */
+const FULL_WIDTH_END = new Set(['。', '！', '？'])
+const KEPT_END = new Set(['?', '!', '？', '！'])
+
+/**
+ * Split what a person typed into the one-box intake into a task title and a description.
+ *
+ * The title is the first line, cut at its first sentence end, and shortened at a word boundary
+ * to {@link DERIVED_TITLE_MAX} with an ellipsis. A question or an exclamation keeps its mark, which
+ * is part of what it says; a period does not. The description is the WHOLE text, unedited,
+ * whenever it says more than the title does: nothing the person wrote is dropped, and the agents
+ * read the description, never the title alone. Returns an empty title for blank input.
+ */
+export function splitDescribedWork(text: string): { title: string; description?: string } {
+  const body = text.trim()
+  if (!body) return { title: '' }
+  const firstLine = body.split(/\r?\n/, 1)[0]!.trim()
+  const title = shorten(firstSentence(firstLine) || firstLine)
+  return stripEnd(title) === stripEnd(body) ? { title } : { title, description: body }
+}
+
+/** The first sentence of a line, ending mark included only when it is `?` or `!`. */
+function firstSentence(line: string): string {
+  const chars = Array.from(line)
+  for (let i = 0; i < chars.length; i++) {
+    const c = chars[i]!
+    const next = chars[i + 1]
+    // A run of dots ("this... later") is ONE mark: only its last dot can end the sentence, and
+    // the whole run is cut with it.
+    if (c === '.' && next === '.') continue
+    const ends =
+      FULL_WIDTH_END.has(c) || ('.!?'.includes(c) && (next === undefined || /\s/.test(next)))
+    if (!ends) continue
+    if (c === '.' && isAbbreviation(chars.slice(0, i).join(''))) continue
+    let end = KEPT_END.has(c) ? i + 1 : i
+    while (c === '.' && end > 0 && chars[end - 1] === '.') end--
+    return chars.slice(0, end).join('').trim()
+  }
+  return line
+}
+
+/** Whether the word before a period is an abbreviation ("e.g", "Dr"), not a sentence's last word. */
+function isAbbreviation(before: string): boolean {
+  const word = before.split(/\s/).pop() ?? ''
+  return ABBREVIATIONS.has(word.toLowerCase())
+}
+
+/** The text without its final sentence mark, so "Fix the login." says no more than "Fix the login". */
+function stripEnd(s: string): string {
+  return s.replace(/[.!?。！？…]+$/u, '')
+}
+
+/** Shorten by CODE POINTS, so a cut never splits an emoji or another astral character in half. */
+function shorten(line: string): string {
+  const chars = Array.from(line)
+  if (chars.length <= DERIVED_TITLE_MAX) return line
+  const cut = chars.slice(0, DERIVED_TITLE_MAX - 1).join('')
+  const lastSpace = cut.lastIndexOf(' ')
+  const keep = lastSpace > cut.length / 2 ? cut.slice(0, lastSpace) : cut
+  return `${keep.trimEnd()}…`
+}

package/app/utils/notificationRoutes.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ExecutionInstance, Notification } from '~/types/domain'
+import {
+  NOTIFICATION_ROUTES,
+  OPEN_TASK_VERB_KEY,
+  notificationTarget,
+  notificationVerbKey,
+  type NotificationRouteDeps,
+} from '~/utils/notificationRoutes'
+import { missingI18nKeys } from '../../test/i18nKeys'
+
+// The card's verb and the place its click lands come from ONE resolution, so a button named for
+// answering never just selects the task. These pin that, and that every verb names a real key.
+
+function deps(instances: ExecutionInstance[] = []): NotificationRouteDeps {
+  return {
+    getInstance: (id) => instances.find((i) => i.id === id),
+    select: vi.fn(),
+    openStepDetail: vi.fn(),
+    openDecision: vi.fn(),
+    openFollowUps: vi.fn(),
+    openForkDecision: vi.fn(),
+    openPrReview: vi.fn(),
+    openBugFishing: vi.fn(),
+    openRequirementReview: vi.fn(),
+    openClarityReview: vi.fn(),
+    openInitiativeTracker: vi.fn(),
+    openOperatorDashboard: vi.fn(),
+  }
+}
+
+const card = (type: Notification['type'], over: Partial<Notification> = {}) =>
+  ({ id: 'n1', type, blockId: 'blk', executionId: 'run', ...over }) as Notification
+
+const run = (steps: unknown[]) => ({ id: 'run', blockId: 'blk', steps }) as ExecutionInstance
+
+describe('notification routes', () => {
+  it('names a real catalog key for every verb', () => {
+    const keys = Object.values(NOTIFICATION_ROUTES)
+      .map((r) => r.verbKey)
+      .filter((k): k is string => k !== null)
+    expect(missingI18nKeys([...keys, OPEN_TASK_VERB_KEY])).toEqual([])
+  })
+
+  it('answers a parked agent question in the decision window', () => {
+    const d = deps([run([{ state: 'waiting_decision', decision: { id: 'dec', chosen: null } }])])
+    const n = card('decision_required')
+    expect(notificationVerbKey(n, d)).toBe('layout.notifications.goTo.answer')
+    notificationTarget(n, d)!.open()
+    expect(d.openDecision).toHaveBeenCalledWith('run', 'dec')
+  })
+
+  it('opens the step for any other park, such as an approval gate', () => {
+    const d = deps([run([{ state: 'done' }, { state: 'waiting_decision' }])])
+    notificationTarget(card('decision_required'), d)!.open()
+    expect(d.openStepDetail).toHaveBeenCalledWith('run', 1)
+  })
+
+  it('says "Open" when only the task can be opened, and opens the task', () => {
+    // The run is not loaded, or it is loaded and not parked (a Ralph loop that gave up).
+    for (const d of [deps(), deps([run([{ state: 'failed' }])])]) {
+      const n = card('decision_required')
+      expect(notificationVerbKey(n, d)).toBe(OPEN_TASK_VERB_KEY)
+      notificationTarget(n, d)!.open()
+      expect(d.select).toHaveBeenCalledWith('blk')
+    }
+    expect(notificationVerbKey(card('fork_decision_pending'), deps())).toBe(OPEN_TASK_VERB_KEY)
+  })
+
+  it('gives no verb to a card whose act button is the action, or that has nowhere to go', () => {
+    expect(notificationVerbKey(card('merge_review'), deps())).toBeNull()
+    expect(notificationVerbKey(card('budget_paused', { blockId: null }), deps())).toBeNull()
+    expect(notificationTarget(card('budget_paused', { blockId: null }), deps())).toBeNull()
+  })
+
+  it('sends a deployment-scoped health alert to the operator dashboard, with no block', () => {
+    const d = deps()
+    notificationTarget(card('platform_health', { blockId: null }), d)!.open()
+    expect(d.openOperatorDashboard).toHaveBeenCalled()
+  })
+})

package/app/utils/notificationRoutes.ts

@@ -0,0 +1,179 @@
+import type { ExecutionInstance, Notification, PipelineStep } from '~/types/domain'
+
+/**
+ * Where each notification takes a person, and the verb that names it (issue #2258, finding F4).
+ *
+ * ONE row per type holds both, so the button's word and the place it opens cannot drift apart:
+ * the inbox's title link and its primary button both dispatch through {@link notificationTarget},
+ * and the verb is decided from the SAME resolution. A route that can only fall back to selecting
+ * the task (its run is not loaded, or not parked) is named "Open", because that is what happens.
+ *
+ * Exhaustive over the notification types, so a new type has to decide. A `null` verb means the
+ * card's own act button already IS the action (Merge, Retry run, Acknowledge), or there is nowhere
+ * to go beyond the card itself.
+ */
+
+/** The store reads and window openers a route needs, injected so this stays testable. */
+export interface NotificationRouteDeps {
+  getInstance: (id: string) => ExecutionInstance | undefined
+  select: (blockId: string) => void
+  openStepDetail: (instanceId: string, stepIndex: number) => void
+  openDecision: (instanceId: string, decisionId: string) => void
+  openFollowUps: (instanceId: string) => void
+  openForkDecision: (instanceId: string) => void
+  openPrReview: (instanceId: string) => void
+  openBugFishing: (instanceId: string) => void
+  openRequirementReview: (blockId: string) => void
+  openClarityReview: (blockId: string) => void
+  openInitiativeTracker: (blockId: string) => void
+  openOperatorDashboard: () => void
+}
+
+/**
+ * Where a click lands. `surface` opens the window that answers the card; `task` only selects the
+ * task on the board, which is the fallback when that window cannot open.
+ */
+export interface NotificationTarget {
+  readonly kind: 'surface' | 'task'
+  readonly open: () => void
+}
+
+interface NotificationRoute {
+  /** The verb for a `surface` target, or null when the card's act button is already the verb. */
+  readonly verbKey: string | null
+  readonly resolve: (n: Notification, deps: NotificationRouteDeps) => NotificationTarget | null
+}
+
+/** The verb for a route that can only select the task. */
+export const OPEN_TASK_VERB_KEY = 'layout.notifications.goTo.open'
+
+const surface = (open: () => void): NotificationTarget => ({ kind: 'surface', open })
+
+/** Select the card's task: the fallback every block-bound route shares. */
+function selectTask(n: Notification, deps: NotificationRouteDeps): NotificationTarget | null {
+  const blockId = n.blockId
+  return blockId ? { kind: 'task', open: () => deps.select(blockId) } : null
+}
+
+/** A window keyed by the card's run, when that run is loaded; else the task. */
+function byRun(open: (deps: NotificationRouteDeps, instanceId: string) => void) {
+  return (n: Notification, deps: NotificationRouteDeps): NotificationTarget | null => {
+    const id = n.executionId
+    if (id && deps.getInstance(id)) return surface(() => open(deps, id))
+    return selectTask(n, deps)
+  }
+}
+
+/** The run's step matching `find`, opened through the universal step dispatch; else the task. */
+function byStep(find: (step: PipelineStep) => boolean) {
+  return (n: Notification, deps: NotificationRouteDeps): NotificationTarget | null => {
+    const instance = n.executionId ? deps.getInstance(n.executionId) : undefined
+    const index = instance?.steps.findIndex(find) ?? -1
+    if (instance && index >= 0) return surface(() => deps.openStepDetail(instance.id, index))
+    return selectTask(n, deps)
+  }
+}
+
+/** A window keyed by the card's block. */
+function byBlock(open: (deps: NotificationRouteDeps, blockId: string) => void) {
+  return (n: Notification, deps: NotificationRouteDeps): NotificationTarget | null => {
+    const blockId = n.blockId
+    return blockId ? surface(() => open(deps, blockId)) : null
+  }
+}
+
+/**
+ * A parked step: an agent's question opens the decision window, where it is answered (as from the
+ * task card and the toolbar); any other park (an approval gate, an iteration cap) opens the step.
+ * A card whose run is not parked, which a Ralph loop or an exhausted gate also raises, opens the
+ * task.
+ */
+function parkedStep(n: Notification, deps: NotificationRouteDeps): NotificationTarget | null {
+  const instance = n.executionId ? deps.getInstance(n.executionId) : undefined
+  const index = instance?.steps.findIndex((s) => s.state === 'waiting_decision') ?? -1
+  const step = instance?.steps[index]
+  if (!instance || !step) return selectTask(n, deps)
+  const decision = step.decision
+  if (decision && !decision.chosen) {
+    return surface(() => deps.openDecision(instance.id, decision.id))
+  }
+  return surface(() => deps.openStepDetail(instance.id, index))
+}
+
+const verb = (leaf: string) => `layout.notifications.goTo.${leaf}`
+
+export const NOTIFICATION_ROUTES: Record<Notification['type'], NotificationRoute> = {
+  merge_review: { verbKey: null, resolve: selectTask },
+  pipeline_complete: { verbKey: null, resolve: selectTask },
+  merge_tag_request: { verbKey: null, resolve: selectTask },
+  ci_failed: { verbKey: null, resolve: selectTask },
+  test_failed: { verbKey: null, resolve: selectTask },
+  deploy_blocked: { verbKey: null, resolve: selectTask },
+  release_regression: { verbKey: null, resolve: selectTask },
+  infra_unreachable: { verbKey: null, resolve: selectTask },
+  key_drift: { verbKey: null, resolve: selectTask },
+  // Raised with no block, so neither has anywhere to go beyond the card.
+  budget_threshold: { verbKey: null, resolve: selectTask },
+  budget_paused: { verbKey: null, resolve: selectTask },
+  // Deployment-scoped: the dashboard holds the live numbers behind the alert.
+  platform_health: { verbKey: null, resolve: (_n, deps) => surface(deps.openOperatorDashboard) },
+  requirement_review: {
+    verbKey: verb('review'),
+    resolve: byBlock((deps, id) => deps.openRequirementReview(id)),
+  },
+  clarity_review: {
+    verbKey: verb('review'),
+    resolve: byBlock((deps, id) => deps.openClarityReview(id)),
+  },
+  decision_required: { verbKey: verb('answer'), resolve: parkedStep },
+  human_test_ready: {
+    verbKey: verb('test'),
+    resolve: byStep((s) => s.agentKind === 'human-test' && s.state === 'waiting_decision'),
+  },
+  visual_confirmation_ready: {
+    verbKey: verb('confirm'),
+    resolve: byStep((s) => s.agentKind === 'visual-confirmation' && s.state === 'waiting_decision'),
+  },
+  human_review: { verbKey: verb('review'), resolve: byStep((s) => s.agentKind === 'human-review') },
+  judge_review: {
+    verbKey: verb('review'),
+    resolve: byStep((s) => s.judge?.status === 'awaiting_decision'),
+  },
+  followup_pending: {
+    verbKey: verb('triage'),
+    resolve: byRun((deps, id) => deps.openFollowUps(id)),
+  },
+  fork_decision_pending: {
+    verbKey: verb('choose'),
+    resolve: byRun((deps, id) => deps.openForkDecision(id)),
+  },
+  pr_review_ready: { verbKey: verb('review'), resolve: byRun((deps, id) => deps.openPrReview(id)) },
+  bug_fishing_triage: {
+    verbKey: verb('triage'),
+    resolve: byRun((deps, id) => deps.openBugFishing(id)),
+  },
+  initiative: {
+    verbKey: verb('open'),
+    resolve: byBlock((deps, id) => deps.openInitiativeTracker(id)),
+  },
+}
+
+/** Where a click on this card lands, or null when it has nowhere to go. */
+export function notificationTarget(
+  n: Notification,
+  deps: NotificationRouteDeps,
+): NotificationTarget | null {
+  return NOTIFICATION_ROUTES[n.type].resolve(n, deps)
+}
+
+/**
+ * The primary button's verb, from the same resolution the click takes: the route's verb when its
+ * window can open, "Open" when only the task can, null when the card has no verb or nowhere to go.
+ */
+export function notificationVerbKey(n: Notification, deps: NotificationRouteDeps): string | null {
+  const route = NOTIFICATION_ROUTES[n.type]
+  if (!route.verbKey) return null
+  const target = route.resolve(n, deps)
+  if (!target) return null
+  return target.kind === 'surface' ? route.verbKey : OPEN_TASK_VERB_KEY
+}

package/app/utils/reviewFriction.ts

@@ -0,0 +1,47 @@
+import type { ReviewFrictionModalContext } from '~/stores/ui/modals'
+import type { parseConflict } from '~/composables/usePipelineErrorToast'
+
+/** A conflict `parseConflict` recognised. */
+type ParsedConflict = NonNullable<ReturnType<typeof parseConflict>>
+
+/** Whether a create was refused by the opt-in review-debt friction gate. */
+export function isReviewDebtConflict(conflict: ParsedConflict | null): conflict is ParsedConflict {
+  return conflict?.reason === 'review_debt_warn' || conflict?.reason === 'review_debt_blocked'
+}
+
+/**
+ * Turn a parsed review-debt friction 409 into the dialog's context (see ReviewFrictionDialog.vue).
+ *
+ * Shared by every surface that creates a task, so the friction reads the same whichever form
+ * raised it. `retry` re-submits with `acknowledgeReviewDebt` and is offered only on the soft
+ * `warn` tier; `pending` is a GETTER over the opener's own in-flight flag, for the reason the
+ * context type documents; `leave` closes the opener when the person leaves to review.
+ */
+export function reviewFrictionContext(
+  conflict: ParsedConflict,
+  retry: () => void,
+  pending: () => boolean,
+  leave: () => void,
+): ReviewFrictionModalContext {
+  const details = conflict.details
+  const rawDebt = Array.isArray(details.debt) ? details.debt : []
+  const debt = rawDebt.map((d) => {
+    const row = (d ?? {}) as { blockId?: unknown; title?: unknown; waitingMinutes?: unknown }
+    return {
+      blockId: typeof row.blockId === 'string' ? row.blockId : '',
+      title: typeof row.title === 'string' ? row.title : null,
+      waitingMinutes: typeof row.waitingMinutes === 'number' ? row.waitingMinutes : 0,
+    }
+  })
+  const isWarn = conflict.reason === 'review_debt_warn'
+  return {
+    kind: isWarn ? 'warn' : 'blocked',
+    reason:
+      details.friction === 'count' || details.friction === 'stuck' ? details.friction : undefined,
+    threshold: typeof details.threshold === 'number' ? details.threshold : null,
+    debt,
+    onConfirm: isWarn ? retry : null,
+    pending,
+    onLeave: leave,
+  }
+}