@cat-factory/app 0.139.0 → 0.141.0

package/app/components/github/RepoTreeBrowser.vue

@@ -7,12 +7,13 @@
 // via `v-model`. The component owns its own navigation/loading state so callers
 // just bind a repo id + mode; it self-loads on mount and when those change.
 //
-// `dir` mode additionally supports `multiple`: instead of the single `v-model`
+// Both modes additionally support `multiple`: instead of the single `v-model`
 // path, the caller passes the current `selectedPaths` (a cart) + `addedPaths`
-// (directories already on the board, shown disabled) and handles the `toggle`
-// event to add/remove a directory. This lets one browse session accumulate
-// several services from ANY parent folder (the monorepo add flow) — navigating
-// away never drops earlier picks.
+// (paths already chosen elsewhere, shown disabled) and handles the `toggle`
+// event to add/remove a path. In `dir` mode this accumulates service directories
+// from ANY parent folder (the monorepo add flow); in `file` mode it accumulates
+// context-document files from anywhere in the tree — navigating away never drops
+// earlier picks.
 import type { RepoTreeEntry } from '~/types/domain'
 
 const props = withDefaults(
@@ -23,11 +24,11 @@ const props = withDefaults(
     modelValue?: string
     /** Directory to open at (e.g. a monorepo service's subdirectory). */
     startPath?: string
-    /** `dir` mode: accumulate a set of picks (via `selectedPaths`/`toggle`) instead of one. */
+    /** Accumulate a set of picks (via `selectedPaths`/`toggle`) instead of one. Either mode. */
     multiple?: boolean
-    /** `dir` + `multiple`: the current cart of picked directories (repo-root-relative). */
+    /** `multiple`: the current cart of picked paths (repo-root-relative). */
     selectedPaths?: string[]
-    /** `dir` + `multiple`: directories already on the board — listed but not selectable. */
+    /** `multiple`: paths already chosen elsewhere — listed but not selectable. */
     addedPaths?: string[]
   }>(),
   { mode: 'dir', startPath: '', multiple: false, selectedPaths: () => [], addedPaths: () => [] },
@@ -182,14 +183,22 @@ watch(
             <button
               type="button"
               class="flex items-center gap-2 truncate text-sm hover:text-primary-400"
-              :class="modelValue === entry.path ? 'text-primary-400' : 'text-slate-300'"
+              :class="isPicked(entry.path) ? 'text-primary-400' : 'text-slate-300'"
+              :disabled="isAdded(entry.path)"
               @click="pick(entry.path)"
             >
               <UIcon name="i-lucide-file" class="h-4 w-4 shrink-0 text-slate-400" />
               <span class="truncate">{{ entry.name }}</span>
             </button>
+            <span
+              v-if="isAdded(entry.path)"
+              class="flex shrink-0 items-center gap-1 text-xs text-slate-500"
+            >
+              <UIcon name="i-lucide-check" class="h-3.5 w-3.5" />
+              {{ t('github.repoTree.added') }}
+            </span>
             <UIcon
-              v-if="modelValue === entry.path"
+              v-else-if="isPicked(entry.path)"
               name="i-lucide-check"
               class="h-4 w-4 shrink-0 text-primary-400"
             />

package/app/components/palettes/AgentPalette.vue

@@ -1,21 +1,29 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { useLocalStorage } from '@vueuse/core'
-import type { AgentKind } from '~/types/domain'
+import { purposeAllowsAgentCategory } from '@cat-factory/contracts'
+import type { AgentKind, PipelinePurpose } from '~/types/domain'
 import { AGENT_CATEGORIES, OBSERVABILITY_GATE_ARCHETYPE } from '~/utils/catalog'
 
 const { t } = useI18n()
 const agents = useAgentsStore()
 const releaseHealth = useReleaseHealthStore()
 defineEmits<{ (e: 'add', kind: AgentKind): void }>()
+// The purpose of the pipeline being built. When set to a non-`build` classifier, the
+// Implementation (`build`) and Testing (`test`) categories are hidden — such a pipeline writes
+// no product code and runs no tests (see `purposeAllowsAgentCategory`). `null`/`build` shows all.
+const props = defineProps<{ purpose?: PipelinePurpose | null }>()
 
 // The post-release-health gate is only meaningful — and only accepted by the backend —
 // with an observability integration connected, so it appears in the palette ONLY then.
-const palette = computed(() =>
-  releaseHealth.connection.connected
+const palette = computed(() => {
+  const all = releaseHealth.connection.connected
     ? [...agents.archetypes, OBSERVABILITY_GATE_ARCHETYPE]
-    : agents.archetypes,
-)
+    : agents.archetypes
+  // Hide the categories the pipeline's purpose doesn't build from (an uncategorized custom kind
+  // has no category to gate, so it always shows).
+  return all.filter((a) => !a.category || purposeAllowsAgentCategory(props.purpose, a.category))
+})
 
 // Group the palette into the ordered catalog categories, plus a trailing "Custom" bucket
 // for runtime-added agents that carry no category. Empty groups are dropped.

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -133,29 +133,16 @@ function setModelPreset(id: string) {
 const selectedPipeline = computed(() =>
   props.block.pipelineId ? pipelines.getPipeline(props.block.pipelineId) : undefined,
 )
-// Hide UI-testing pipelines when this task's frame has no UI to exercise, and `'recurring'`-only
-// pipelines (the task's manual Run control can't start one) — they'd be refused at run start
-// (see utils/pipeline + the backend gate).
+// Hide UI-testing pipelines when this task's frame has no UI to exercise, `'recurring'`-only
+// pipelines (the task's manual Run control can't start one), and — for a `document` task — every
+// non-document pipeline (it authors a doc, so a build/test pipeline makes no sense). All would be
+// refused / wrong at run start (see utils/pipeline + the backend gate + the purpose classifier).
 const taskFrame = computed(() => board.serviceOf(props.block))
 const selectablePipelines = computed(() =>
   pipelines.pipelines.filter((p) =>
-    pipelineAllowedForManualStart(p, taskFrame.value, board.blocks),
+    pipelineAllowedForManualStart(p, taskFrame.value, board.blocks, props.block.taskType),
   ),
 )
-const pipelineMenu = computed(() => [
-  [
-    {
-      label: t('inspector.runSettings.noDefault'),
-      icon: 'i-lucide-rotate-ccw',
-      onSelect: () => setPipeline(''),
-    },
-    ...selectablePipelines.value.map((p) => ({
-      label: p.name,
-      icon: 'i-lucide-workflow',
-      onSelect: () => setPipeline(p.id),
-    })),
-  ],
-])
 function setPipeline(id: string) {
   board.updateBlock(props.block.id, { pipelineId: id })
 }
@@ -271,15 +258,22 @@ const technicalLabel = computed(() => {
         <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
           {{ t('inspector.runSettings.pipeline') }}
         </span>
-        <UDropdownMenu :items="pipelineMenu">
-          <UButton
-            size="xs"
-            variant="ghost"
-            color="neutral"
-            icon="i-lucide-workflow"
-            trailing-icon="i-lucide-chevron-down"
-          />
-        </UDropdownMenu>
+        <PipelinePicker
+          :model-value="block.pipelineId ?? ''"
+          :options="selectablePipelines"
+          :none-label="t('inspector.runSettings.noDefault')"
+          @update:model-value="setPipeline"
+        >
+          <template #trigger>
+            <UButton
+              size="xs"
+              variant="ghost"
+              color="neutral"
+              icon="i-lucide-workflow"
+              trailing-icon="i-lucide-chevron-down"
+            />
+          </template>
+        </PipelinePicker>
       </div>
       <div v-if="selectedPipeline" class="flex items-center gap-1">
         <UBadge

package/app/components/pipeline/PipelineBuilder.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
-import type { AgentKind, Pipeline } from '~/types/domain'
+import { purposeAllowsAgentCategory } from '@cat-factory/contracts'
+import type { AgentKind, Pipeline, PipelinePurpose } from '~/types/domain'
 import AgentPalette from '~/components/palettes/AgentPalette.vue'
 import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 import {
@@ -22,6 +23,18 @@ const CONSENSUS_STRATEGIES = computed<{ value: ConsensusStrategy; label: string
   { value: 'ranked-voting', label: t('pipeline.builder.strategyOption.ranked-voting') },
 ])
 
+// The use-case classifier options for the pipeline (its `purpose`). Static literal `t()` keys, one
+// per `PIPELINE_PURPOSES` member, so the typed-message-keys check sees them (a runtime-built key
+// wouldn't be checkable). A non-`build` purpose hides the Implementation/Testing agent kinds in
+// the palette below (see `AgentPalette`), and drives which task pickers offer the saved pipeline.
+const PURPOSE_OPTIONS = computed<{ value: PipelinePurpose; label: string }[]>(() => [
+  { value: 'build', label: t('pipeline.builder.purposeOption.build') },
+  { value: 'document', label: t('pipeline.builder.purposeOption.document') },
+  { value: 'review', label: t('pipeline.builder.purposeOption.review') },
+  { value: 'research', label: t('pipeline.builder.purposeOption.research') },
+  { value: 'planning', label: t('pipeline.builder.purposeOption.planning') },
+])
+
 /** Add a blank participant to the draft step's consensus config. */
 function addParticipant(i: number) {
   const cfg = pipelines.draftConsensus[i]
@@ -56,6 +69,19 @@ const skillStepNeedsPick = computed(() =>
   ),
 )
 
+// Steps whose agent category the chosen purpose forbids (a non-`build` purpose writes no code and
+// runs no tests, so the Implementation/Testing categories are disallowed — see
+// `purposeAllowsAgentCategory`). The palette hides those kinds, so this is only reachable by
+// switching an existing draft to a non-`build` purpose AFTER such steps were added. The backend has
+// no kind→category map to gate on, so the builder is the enforcement point: save is blocked until
+// the offending steps are removed (or the purpose set back to Build).
+const stepsDisallowedByPurpose = computed(() =>
+  pipelines.draft.filter((kind) => {
+    const category = agentKindMeta(kind).category
+    return !!category && !purposeAllowsAgentCategory(pipelines.draftPurpose, category)
+  }),
+)
+
 // A step's picked skill id is no longer in the account catalog (the source dir was renamed or
 // unlinked). The step will fail cleanly at dispatch; flag it so the user re-picks.
 function skillMissing(index: number): boolean {
@@ -282,7 +308,7 @@ async function clone(p: Pipeline) {
             </UButton>
           </div>
           <div class="flex-1 pe-1 lg:min-h-0 lg:overflow-y-auto">
-            <AgentPalette @add="add" />
+            <AgentPalette :purpose="pipelines.draftPurpose" @add="add" />
           </div>
         </div>
 
@@ -310,6 +336,34 @@ async function clone(p: Pipeline) {
             class="mb-2"
           />
 
+          <!-- Purpose: the pipeline's use-case classifier. Drives which task pickers offer it (a
+               document task offers only `document` pipelines) and narrows the palette below (a
+               non-build purpose hides the Implementation/Testing kinds). -->
+          <div class="mb-2 flex items-center gap-2">
+            <label class="shrink-0 text-[11px] font-medium text-slate-400">
+              {{ t('pipeline.builder.purposeLabel') }}
+            </label>
+            <USelect
+              :model-value="pipelines.draftPurpose ?? undefined"
+              :items="PURPOSE_OPTIONS"
+              value-key="value"
+              size="sm"
+              class="min-w-40"
+              :placeholder="t('pipeline.builder.purposePlaceholder')"
+              @update:model-value="pipelines.draftPurpose = $event"
+            />
+          </div>
+
+          <!-- Description: the prose summary shown next to the step list in the pipeline pickers. -->
+          <UTextarea
+            v-model="pipelines.draftDescription"
+            :placeholder="t('pipeline.builder.descriptionPlaceholder')"
+            :rows="2"
+            autoresize
+            size="sm"
+            class="mb-2 w-full"
+          />
+
           <!-- Labels: organize the pipeline in the library (filter/search). -->
           <div class="mb-3 flex flex-wrap items-center gap-1.5">
             <UBadge
@@ -350,6 +404,14 @@ async function clone(p: Pipeline) {
             {{ t('pipeline.builder.skillNeedsPick') }}
           </p>
 
+          <p
+            v-if="stepsDisallowedByPurpose.length"
+            class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
+          >
+            <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
+            {{ t('pipeline.builder.purposeStepsConflict') }}
+          </p>
+
           <div
             v-if="pipelines.draft.length === 0"
             class="flex flex-1 items-center justify-center rounded-lg border border-dashed border-slate-700 p-4 text-center text-xs text-slate-500"
@@ -1005,7 +1067,7 @@ async function clone(p: Pipeline) {
           color="primary"
           icon="i-lucide-save"
           size="sm"
-          :disabled="pipelines.draft.length === 0"
+          :disabled="pipelines.draft.length === 0 || stepsDisallowedByPurpose.length > 0"
           @click="save"
         >
           {{ pipelines.editingId ? t('pipeline.builder.update') : t('pipeline.builder.save') }}

package/app/components/pipeline/PipelinePicker.vue

@@ -0,0 +1,120 @@
+<script setup lang="ts">
+// The rich pipeline picker used wherever a pipeline is chosen (add-task modal, inspector run
+// settings). A master–detail popover: the left column lists the selectable pipelines (plus a
+// "none / choose at run time" row), and hovering a row reveals that pipeline's full preview — its
+// description + the ordered agent steps — in the right column, so a user sees exactly what a
+// pipeline does before picking it. The trigger is customizable via the `#trigger` slot (the
+// inspector uses a bare icon button; the modal a full-width labelled one).
+import { computed, ref } from 'vue'
+import type { Pipeline } from '~/types/domain'
+
+const props = withDefaults(
+  defineProps<{
+    /** Selected pipeline id, or '' for the "none" option. */
+    modelValue: string
+    /** The pipelines offered (already filtered for the surface, e.g. manual-start allowed). */
+    options: Pipeline[]
+    /** Label for the "none" row (e.g. "Choose at run time" / "No default"). */
+    noneLabel: string
+    /** Extra classes for the default trigger button (e.g. full-width in the modal). */
+    triggerClass?: string
+  }>(),
+  { triggerClass: '' },
+)
+
+const emit = defineEmits<{ 'update:modelValue': [string] }>()
+const { t } = useI18n()
+
+const open = ref(false)
+// The row currently hovered, driving the right-column preview. `undefined` ⇒ fall back to the
+// selected pipeline; the sentinel '' means the "none" row is hovered (show the none hint).
+const hoverId = ref<string | undefined>(undefined)
+
+const selected = computed(() => props.options.find((p) => p.id === props.modelValue))
+const triggerLabel = computed(() => selected.value?.name ?? props.noneLabel)
+
+/** The pipeline the right pane previews: the hovered row, else the current selection. */
+const previewPipeline = computed<Pipeline | null>(() => {
+  const id = hoverId.value ?? props.modelValue
+  return id ? (props.options.find((p) => p.id === id) ?? null) : null
+})
+
+function choose(id: string) {
+  emit('update:modelValue', id)
+  open.value = false
+}
+</script>
+
+<template>
+  <UPopover v-model:open="open" :content="{ align: 'start' }">
+    <slot name="trigger" :label="triggerLabel">
+      <UButton
+        color="neutral"
+        variant="subtle"
+        size="sm"
+        icon="i-lucide-workflow"
+        trailing-icon="i-lucide-chevron-down"
+        :class="triggerClass"
+        data-testid="pipeline-picker-trigger"
+      >
+        {{ triggerLabel }}
+      </UButton>
+    </slot>
+
+    <template #content>
+      <div
+        class="flex max-h-[24rem] w-[min(44rem,94vw)]"
+        data-testid="pipeline-picker-panel"
+        @mouseleave="hoverId = undefined"
+      >
+        <!-- left: selectable options -->
+        <ul class="w-1/2 shrink-0 overflow-y-auto border-e border-slate-800 p-1">
+          <li>
+            <button
+              type="button"
+              class="flex w-full items-center gap-2 rounded px-2 py-1.5 text-start text-sm hover:bg-slate-800/60"
+              :class="modelValue ? 'text-slate-300' : 'text-slate-100'"
+              data-testid="pipeline-option-none"
+              @mouseenter="hoverId = ''"
+              @click="choose('')"
+            >
+              <UIcon name="i-lucide-rotate-ccw" class="h-4 w-4 shrink-0 text-slate-400" />
+              <span class="flex-1 truncate">{{ noneLabel }}</span>
+              <UIcon
+                v-if="!modelValue"
+                name="i-lucide-check"
+                class="h-4 w-4 shrink-0 text-primary-400"
+              />
+            </button>
+          </li>
+          <li v-for="p in options" :key="p.id">
+            <button
+              type="button"
+              class="flex w-full items-center gap-2 rounded px-2 py-1.5 text-start text-sm hover:bg-slate-800/60"
+              :class="modelValue === p.id ? 'text-slate-100' : 'text-slate-300'"
+              :data-testid="`pipeline-option-${p.id}`"
+              @mouseenter="hoverId = p.id"
+              @click="choose(p.id)"
+            >
+              <UIcon name="i-lucide-workflow" class="h-4 w-4 shrink-0 text-slate-400" />
+              <span class="flex-1 truncate">{{ p.name }}</span>
+              <UIcon
+                v-if="modelValue === p.id"
+                name="i-lucide-check"
+                class="h-4 w-4 shrink-0 text-primary-400"
+              />
+            </button>
+          </li>
+        </ul>
+
+        <!-- right: preview of the hovered (or selected) pipeline -->
+        <div class="w-1/2 overflow-y-auto p-3">
+          <PipelinePreview v-if="previewPipeline" :pipeline="previewPipeline" />
+          <div v-else class="text-[12px] leading-snug text-slate-500">
+            {{ t('pipeline.picker.noneHint') }}
+          </div>
+        </div>
+      </div>
+    </template>
+  </UPopover>
+</template>

package/app/components/pipeline/PipelinePreview.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+// A compact, read-only summary of a pipeline: its name, prose description (when authored), and the
+// ordered list of enabled agent steps rendered as icon+label chips (a human-gated step is flagged).
+// Shared by the pipeline pickers' hover preview so "what a pipeline consists of" is explained the
+// same way everywhere. Resolves each step's display metadata through the single `agentKindMeta`
+// path (via <AgentKindIcon>), so a system/custom kind can never blow up the renderer.
+import { computed } from 'vue'
+import type { Pipeline } from '~/types/domain'
+import { pipelineDisplaySteps } from '~/utils/pipeline'
+
+const props = defineProps<{ pipeline: Pipeline }>()
+const { t } = useI18n()
+
+const steps = computed(() => pipelineDisplaySteps(props.pipeline))
+</script>
+
+<template>
+  <div class="space-y-2" data-testid="pipeline-preview">
+    <div class="text-sm font-semibold text-slate-100">{{ pipeline.name }}</div>
+    <p
+      v-if="pipeline.description"
+      class="text-[12px] leading-snug text-slate-400"
+      data-testid="pipeline-preview-description"
+    >
+      {{ pipeline.description }}
+    </p>
+    <div>
+      <div class="mb-1 flex items-center gap-1 text-[10px] uppercase tracking-wide text-slate-500">
+        <UIcon name="i-lucide-workflow" class="h-3 w-3" />
+        {{ t('pipeline.preview.stepCount', { count: steps.length }, steps.length) }}
+      </div>
+      <ol class="flex flex-wrap items-center gap-1">
+        <li
+          v-for="(s, i) in steps"
+          :key="i"
+          class="inline-flex items-center gap-1 rounded bg-slate-800/70 px-1.5 py-0.5"
+        >
+          <AgentKindIcon :kind="s.kind" show-label icon-class="h-3.5 w-3.5" />
+          <UIcon
+            v-if="s.gated"
+            name="i-lucide-shield-check"
+            class="h-3 w-3 text-amber-400"
+            :title="t('pipeline.preview.gated')"
+          />
+        </li>
+      </ol>
+    </div>
+  </div>
+</template>

package/app/composables/api/github.ts

@@ -13,6 +13,7 @@ import {
   listGitHubIssuesContract,
   listGitHubPullsContract,
   listGitHubReposContract,
+  listGitHubRepoFilesContract,
   listGitHubRepoTreeContract,
   mergeGitHubPullRequestContract,
   openGitHubPullRequestContract,
@@ -92,6 +93,13 @@ export function githubApi({ send, ws }: ApiContext) {
         queryParams: { path },
       }),
 
+    // List every file in a repo (whole tree, one recursive read) for file-path search.
+    listGitHubRepoFiles: (workspaceId: string, repoGithubId: number) =>
+      send(listGitHubRepoFilesContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { repoGithubId: String(repoGithubId) },
+      }),
+
     listGitHubBranches: (workspaceId: string, repoGithubId: number) =>
       send(listGitHubBranchesContract, {
         pathPrefix: ws(workspaceId),

package/app/composables/useContextLinking.spec.ts

@@ -0,0 +1,138 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  buildLinkFailureReport,
+  contextKey,
+  type LinkFailure,
+  type PendingContext,
+  useContextLinking,
+} from '~/composables/useContextLinking'
+
+// The context-linking path used to swallow every attachment failure into a bare count.
+// `buildLinkFailureReport` is the pure diagnostic dump the "Copy details" toast action
+// puts on the clipboard, so it must carry the item coordinates, the HTTP status + backend
+// code, and the server's message — the exact context a bug report needs.
+
+function item(overrides: Partial<PendingContext> = {}): PendingContext {
+  return {
+    kind: 'document',
+    source: 'github',
+    externalId: 'acme/repo:docs/x.md',
+    title: 'x.md',
+    needsImport: true,
+    ...overrides,
+  }
+}
+
+describe('buildLinkFailureReport', () => {
+  it('captures every failure with its coordinates, status, code, and message', () => {
+    const failures: LinkFailure[] = [
+      {
+        item: item(),
+        message: 'GitHub denied access to "docs/x.md" in acme/repo (HTTP 403).',
+        status: 403,
+        code: 'conflict',
+      },
+    ]
+
+    const report = buildLinkFailureReport(failures, {
+      workspaceId: 'ws_1',
+      blockId: 'blk_1',
+      when: '2026-07-19T00:00:00.000Z',
+    })
+
+    expect(report).toContain('Context link failures: 1')
+    expect(report).toContain('workspace: ws_1')
+    expect(report).toContain('block: blk_1')
+    expect(report).toContain('document/github: acme/repo:docs/x.md')
+    expect(report).toContain('status: 403')
+    expect(report).toContain('code: conflict')
+    expect(report).toContain('error: GitHub denied access')
+  })
+
+  it('omits absent optional fields (no status/code/context)', () => {
+    const report = buildLinkFailureReport([{ item: item(), message: 'network error' }])
+    expect(report).toContain('Context link failures: 1')
+    expect(report).not.toContain('status:')
+    expect(report).not.toContain('code:')
+    expect(report).not.toContain('workspace:')
+    expect(report).toContain('error: network error')
+  })
+
+  it('dumps the backend details bag, distinguishing the upstream status from the HTTP status', () => {
+    const report = buildLinkFailureReport([
+      {
+        item: item(),
+        message: 'GitHub denied access to "docs/x.md" in acme/repo (HTTP 403).',
+        status: 409,
+        code: 'conflict',
+        details: { owner: 'acme', repo: 'repo', path: 'docs/x.md', status: 403 },
+      },
+    ])
+    // The mapped HTTP status and the upstream GitHub status are both present, unambiguously.
+    expect(report).toContain('status: 409')
+    expect(report).toContain('details.status: 403')
+    expect(report).toContain('details.owner: acme')
+    expect(report).toContain('details.path: docs/x.md')
+  })
+})
+
+describe('contextKey', () => {
+  it('is stable and distinguishes kind/source/externalId', () => {
+    expect(contextKey(item())).toBe('document:github:acme/repo:docs/x.md')
+    expect(contextKey(item({ kind: 'task', source: 'github' }))).toBe(
+      'task:github:acme/repo:docs/x.md',
+    )
+  })
+})
+
+describe('presentLinkFailures', () => {
+  // Stub the Nuxt auto-imports `useContextLinking` pulls in, so the toast-orchestration
+  // side of the composable can be exercised without a full Nuxt runtime.
+  function stub() {
+    const add = vi.fn()
+    // `copyAction` echoes the text it would copy so we can assert the report content.
+    const copyAction = vi.fn((text: string) => ({ label: 'copy', text, onClick: () => {} }))
+    vi.stubGlobal('useDocumentsStore', () => ({}))
+    vi.stubGlobal('useTasksStore', () => ({}))
+    vi.stubGlobal('useWorkspaceStore', () => ({ workspaceId: 'ws_1' }))
+    vi.stubGlobal('useToast', () => ({ add }))
+    vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
+    vi.stubGlobal('useCopyToClipboard', () => ({ copyAction }))
+    return { add, copyAction }
+  }
+
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('is a no-op when nothing failed', () => {
+    const { add } = stub()
+    useContextLinking().presentLinkFailures([])
+    expect(add).not.toHaveBeenCalled()
+  })
+
+  it('raises one sticky, actionable toast whose Copy action carries the full report', () => {
+    const { add, copyAction } = stub()
+    const failures: LinkFailure[] = [
+      {
+        item: item(),
+        message: 'GitHub denied access to "docs/x.md" in acme/repo (HTTP 403).',
+        status: 409,
+        code: 'conflict',
+        details: { owner: 'acme', repo: 'repo', path: 'docs/x.md', status: 403 },
+      },
+    ]
+    useContextLinking().presentLinkFailures(failures, 'blk_1')
+
+    expect(add).toHaveBeenCalledTimes(1)
+    const toast = add.mock.calls[0]![0]
+    // Sticky so the cause stays readable, titled by the count key, and per-item reason shown.
+    expect(toast.title).toBe('board.addTask.linkFailed')
+    expect(toast.duration).toBe(0)
+    expect(toast.description).toContain('GitHub denied access')
+    expect(toast.actions).toHaveLength(1)
+    // The Copy action's payload is the full diagnostic report (block + upstream status).
+    const report = copyAction.mock.calls[0]![0]
+    expect(report).toContain('block: blk_1')
+    expect(report).toContain('details.status: 403')
+    expect(toast.actions[0]).toMatchObject({ text: report })
+  })
+})