@cat-factory/app 0.235.0 → 0.236.1

package/README.md

@@ -79,6 +79,30 @@ earlier than before takes the entire SPA down at boot, and the unit suite cannot
 (nothing there installs the plugin). Every e2e spec does, because every one of them boots
 the app.
 
+### The persisted board pin is UNVALIDATED until `init()` resolves it
+
+`workspace.workspaceId` is restored from persisted state SYNCHRONOUSLY, before any request fires,
+so every `immediate: true` watcher on it (`pages/index.vue`) runs against an id nothing has
+checked. The pin can name a board that was deleted, or one whose access was revoked while the
+browser held it, and the RBAC gate answers both with a 404 (it hides a denial as a not-found, so
+existence never leaks). `init()` then validates the pin against `GET /workspaces` and re-points it
+at a board the user can actually reach.
+
+Firing the per-board reads on the pin anyway is deliberate: it overlaps them with the workspace
+list instead of queueing them behind it, which is why `init()` fetches the pinned SNAPSHOT
+speculatively too. **What travels with that is the miss.** Each of those boot reads states its own
+tolerance at its own seam (`init`'s `.catch(() => null)`, `github.ensureProbed`'s internal catch,
+`models.prefetchForBoard`), because a 404 there is an expected outcome and not a fault: the
+watcher fires again for the board init resolved, which is the read that counts. A bare
+`void store.load(workspace.workspaceId)` in that chain is an uncaught rejection in a real user's
+browser, and the e2e suite's `pageErrors` fixture fails the spec that boots a session whose access
+was just revoked.
+
+Tolerating the miss is not the same as pretending it succeeded: a dropped load leaves its store
+UNLOADED (`models.loaded` stays false, so `useAiReadiness().ready` is false), which reads as
+unresolved rather than as a board with nothing configured, and leaves the next caller free to
+retry. Pin new boot reads with a store-level unit test (`stores/models.spec.ts`).
+
 ### A backend-DECLARED form renders through `DescriptorFields.vue`
 
 When the backend declares the fields and the SPA only collects them, render them with the shared

package/app/components/auth/LoginScreen.vue

@@ -205,7 +205,10 @@ const noSignInMethod = computed(
 </script>
 
 <template>
-  <div class="flex h-screen w-screen items-center justify-center bg-slate-950 text-slate-100">
+  <div
+    class="flex h-screen w-screen items-center justify-center bg-slate-950 text-slate-100"
+    data-testid="login-screen"
+  >
     <div
       class="w-full max-w-sm rounded-xl border border-slate-800 bg-slate-900/80 p-8 backdrop-blur"
     >
@@ -392,6 +395,7 @@ const noSignInMethod = computed(
           icon="i-lucide-at-sign"
           size="lg"
           class="w-full"
+          data-testid="login-email"
         />
         <SecretInput
           v-model="password"
@@ -400,9 +404,17 @@ const noSignInMethod = computed(
           icon="i-lucide-lock"
           size="lg"
           class="w-full"
+          data-testid="login-password"
         />
-        <p v-if="error" class="text-sm text-rose-400">{{ error }}</p>
-        <UButton block size="lg" color="primary" type="submit" :loading="busy">
+        <p v-if="error" class="text-sm text-rose-400" data-testid="login-error">{{ error }}</p>
+        <UButton
+          block
+          size="lg"
+          color="primary"
+          type="submit"
+          :loading="busy"
+          data-testid="login-submit"
+        >
           {{ mode === 'signup' ? t('auth.login.createAccount') : t('auth.login.signIn') }}
         </UButton>
         <p class="text-center text-xs text-slate-400">

package/app/components/auth/UserMenu.vue

@@ -35,6 +35,7 @@ const items = computed<DropdownMenuItem[][]>(() => [
   <UDropdownMenu v-if="auth.user" :items="items" :content="{ side: 'top', align: 'start' }">
     <button
       type="button"
+      data-testid="user-menu"
       :title="collapsed ? auth.user.name || auth.user.login : undefined"
       class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-start transition hover:bg-slate-800/60"
       :class="collapsed ? 'justify-center' : ''"

package/app/components/board/AddTaskModal.vue

@@ -57,7 +57,7 @@ const fragments = useFragmentsStore()
 const toast = useToast()
 const { t } = useI18n()
 
-const { linkPending, presentLinkFailures } = useContextLinking()
+const { resolvePending, linkPending, presentLinkFailures } = useContextLinking()
 
 const open = computed(() => ui.addTaskContainerId !== null)
 
@@ -453,8 +453,13 @@ const resolvingIssueBodies = ref(false)
 // A staged issue picked from search results carries no body yet (`needsImport`, and the
 // search result has no description). Resolve it once the form opens — from the local cache
 // when already imported, else by importing it (idempotent; we'd import on add anyway) — so
-// its description can be shown read-only and folded into the task. Best-effort: a failure
-// just leaves that issue without a preview, still linked on add.
+// its description can be shown read-only and folded into the task.
+//
+// Non-fatal (the form still opens), but NOT silent: an issue this cannot read is the very issue
+// that will block the submit, since the fetch moved ahead of the create. Recording the cause on the
+// item is what turns that into a warning the author sees NOW, on a chip they can remove, instead of
+// a create refused seconds later for a reason nothing on the form ever mentioned. A tracker
+// reference has no `parseRef`-style pre-flight to ask, so this attempt IS its pre-flight.
 async function resolvePendingIssueBodies() {
   const unresolved = pendingContext.value.filter(
     (c) => c.kind === 'task' && !(c.description ?? '').trim(),
@@ -463,6 +468,7 @@ async function resolvePendingIssueBodies() {
   resolvingIssueBodies.value = true
   try {
     const resolved: Record<string, string> = {}
+    const failed: Record<string, string> = {}
     for (const item of unresolved) {
       const source = item.source as TaskSourceKind
       const cached = tasks.tasks.find(
@@ -476,15 +482,16 @@ async function resolvePendingIssueBodies() {
       try {
         const imported = await tasks.importTask(source, item.externalId)
         if ((imported.description ?? '').trim()) resolved[contextKey(item)] = imported.description
-      } catch {
-        // Unreadable/forbidden issue — skip the preview; it still links on add.
+      } catch (e) {
+        failed[contextKey(item)] = e instanceof Error ? e.message : String(e)
       }
     }
-    if (Object.keys(resolved).length) {
-      // The issue is now imported, so it links directly on add (needsImport → false).
+    if (Object.keys(resolved).length || Object.keys(failed).length) {
       pendingContext.value = pendingContext.value.map((c) => {
-        const body = resolved[contextKey(c)]
-        return body ? { ...c, description: body, needsImport: false } : c
+        const key = contextKey(c)
+        // The issue is now imported, so it links directly on add (needsImport → false).
+        if (resolved[key]) return { ...c, description: resolved[key], needsImport: false }
+        return failed[key] ? { ...c, unreadable: failed[key] } : c
       })
     }
   } finally {
@@ -642,6 +649,18 @@ async function submitCreate(acknowledgeReviewDebt: boolean) {
   if (!containerId) return
   saving.value = true
   try {
+    // Attachments are fetched BEFORE the task is written. A page that moved, a token without
+    // access or a source that is down is a correction the user can still make with the form in
+    // front of them; the same failure after the create leaves a task carrying context it never
+    // got, reported by a toast over a closed dialog.
+    const { resolved, failures } = await resolvePending(pendingContext.value)
+    pendingContext.value = resolved
+    if (failures.length) {
+      presentLinkFailures(failures, undefined, {
+        title: (count) => t('board.addTask.contextFailed', { count }, count),
+      })
+      return
+    }
     const typeFields = buildTypeFields()
     // The saved description includes each linked issue's body (shown read-only above)
     // followed by the user's own notes, so the original issue description is part of the
@@ -672,9 +691,9 @@ async function submitCreate(acknowledgeReviewDebt: boolean) {
       ...(acknowledgeReviewDebt ? { acknowledgeReviewDebt: true } : {}),
     })
     if (block) {
-      // Surface the SPECIFIC cause of any attachment that couldn't be linked (a GitHub
-      // permission/visibility error, a not-found doc, …) instead of a bare count, plus a
-      // one-click "Copy details" for a bug report.
+      // Everything reachable was fetched above, so what can still fail here is the LINK itself
+      // (a doc another task already holds). Surfaced with its specific cause plus a one-click
+      // "Copy details" for a bug report, and after the create because the task is already sound.
       presentLinkFailures(await linkPending(block.id, pendingContext.value), block.id)
     }
     ui.closeReviewFriction()

package/app/components/board/CreateInitiativeModal.vue

@@ -32,7 +32,7 @@ const board = useBoardStore()
 const initiatives = useInitiativesStore()
 const toast = useToast()
 const { t } = useI18n()
-const { linkPending, presentLinkFailures } = useContextLinking()
+const { resolvePending, linkPending, presentLinkFailures } = useContextLinking()
 
 const open = computed({
   get: () => ui.createInitiativeFrameId !== null,
@@ -56,6 +56,14 @@ const description = ref('')
 const inputs = ref<InitiativePresetInputs>({})
 // Context the user chose to attach, committed once the initiative block exists (see create()).
 const pendingContext = ref<PendingContext[]>([])
+/**
+ * Whether THIS form is mid-submit. `initiatives.creating` cannot answer that any more: it is set
+ * inside `initiatives.create`, which the attachment fetch in `create()` now runs several network
+ * round trips ahead of. Through those seconds the button looked idle and enabled, and a second click
+ * re-entered with the ORIGINAL `pendingContext` (reassigned only after every import settles),
+ * re-imported everything and created a SECOND initiative. The add-task form's `saving` is the model.
+ */
+const submitting = ref(false)
 
 // Monotonic token so a slow probe response from a since-changed preset/frame is discarded.
 let probeSeq = 0
@@ -108,6 +116,7 @@ watch(open, (o) => {
   if (!o) return
   title.value = ''
   description.value = ''
+  submitting.value = false
   pendingContext.value = []
   selectedPresetId.value = GENERIC_PRESET_ID
   applyPreset()
@@ -119,14 +128,30 @@ const presetProblems = computed(() =>
   selectedPreset.value ? validateInitiativePresetInputs(selectedPreset.value, inputs.value) : [],
 )
 const canSubmit = computed(
-  () => title.value.trim().length > 0 && presetProblems.value.length === 0 && !initiatives.creating,
+  () =>
+    title.value.trim().length > 0 &&
+    presetProblems.value.length === 0 &&
+    !submitting.value &&
+    !initiatives.creating,
 )
 
 async function create() {
   const frameId = ui.createInitiativeFrameId
   if (!frameId || !canSubmit.value) return
   const descriptor = selectedPreset.value
+  submitting.value = true
   try {
+    // Attachments are fetched BEFORE the initiative is written, for the reason the add-task form
+    // does it: an unreachable page is a correction the user can still make here, where the same
+    // failure after the create leaves an initiative carrying context it never got.
+    const { resolved, failures } = await resolvePending(pendingContext.value)
+    pendingContext.value = resolved
+    if (failures.length) {
+      presentLinkFailures(failures, undefined, {
+        title: (count) => t('initiative.create.contextFailed', { count }, count),
+      })
+      return
+    }
     const { block } = await initiatives.create(frameId, {
       title: title.value.trim(),
       description: description.value.trim() || undefined,
@@ -135,9 +160,9 @@ async function create() {
         ? sanitizeInitiativePresetInputs(descriptor, inputs.value)
         : undefined,
     })
-    // Surface the SPECIFIC cause of any attachment that couldn't be linked (a GitHub
-    // permission/visibility error, a not-found doc, …) rather than a bare count. The initiative
-    // itself is already created, so a failed attachment never costs the user the form.
+    // Everything reachable was fetched above, so what can still fail here is the LINK itself (a
+    // doc another task already holds), surfaced with its specific cause rather than a bare count.
+    // The initiative is already created, so a failed link never costs the user the form.
     presentLinkFailures(await linkPending(block.id, pendingContext.value), block.id, {
       title: (count) => t('initiative.create.linkFailed', { count }, count),
     })
@@ -151,6 +176,8 @@ async function create() {
       icon: 'i-lucide-triangle-alert',
       color: 'error',
     })
+  } finally {
+    submitting.value = false
   }
 }
 </script>
@@ -266,7 +293,7 @@ async function create() {
         <UButton
           data-testid="create-initiative-submit"
           color="primary"
-          :loading="initiatives.creating"
+          :loading="submitting || initiatives.creating"
           :disabled="!canSubmit"
           @click="create"
         >

package/app/components/context/ContextAttachmentFields.vue

@@ -167,29 +167,38 @@ function removePending(item: PendingContext) {
         <div
           v-for="item in pendingDocs"
           :key="contextKey(item)"
-          class="flex items-center gap-1.5 rounded-md border border-slate-800 bg-slate-900/60 px-2 py-1.5 text-xs text-slate-300"
+          class="rounded-md border border-slate-800 bg-slate-900/60"
         >
-          <UIcon
-            :name="item.icon ?? 'i-lucide-file-text'"
-            class="h-3.5 w-3.5 shrink-0 text-indigo-400"
-          />
-          <span class="truncate">{{ item.title }}</span>
-          <UBadge
-            v-if="item.needsImport"
-            color="neutral"
-            variant="soft"
-            size="xs"
-            class="ms-1 shrink-0"
+          <div class="flex items-center gap-1.5 px-2 py-1.5 text-xs text-slate-300">
+            <UIcon
+              :name="item.icon ?? 'i-lucide-file-text'"
+              class="h-3.5 w-3.5 shrink-0 text-indigo-400"
+            />
+            <span class="truncate">{{ item.title }}</span>
+            <UBadge
+              v-if="item.needsImport"
+              color="neutral"
+              variant="soft"
+              size="xs"
+              class="ms-1 shrink-0"
+            >
+              {{ t('contextAttachments.importsOnAdd') }}
+            </UBadge>
+            <button
+              type="button"
+              class="ms-auto shrink-0 text-slate-400 hover:text-slate-200"
+              @click="removePending(item)"
+            >
+              <UIcon name="i-lucide-x" class="h-3.5 w-3.5" />
+            </button>
+          </div>
+          <p
+            v-if="item.unreadable"
+            class="px-2 pb-1.5 text-[11px] text-amber-400"
+            data-testid="context-item-unreadable"
           >
-            {{ t('contextAttachments.importsOnAdd') }}
-          </UBadge>
-          <button
-            type="button"
-            class="ms-auto shrink-0 text-slate-400 hover:text-slate-200"
-            @click="removePending(item)"
-          >
-            <UIcon name="i-lucide-x" class="h-3.5 w-3.5" />
-          </button>
+            {{ t('contextAttachments.unreadable', { error: item.unreadable }) }}
+          </p>
         </div>
       </div>
       <p v-else class="text-[11px] text-slate-500">
@@ -266,29 +275,41 @@ function removePending(item: PendingContext) {
         <div
           v-for="item in pendingIssues"
           :key="contextKey(item)"
-          class="flex items-center gap-1.5 rounded-md border border-slate-800 bg-slate-900/60 px-2 py-1.5 text-xs text-slate-300"
+          class="rounded-md border border-slate-800 bg-slate-900/60"
         >
-          <UIcon
-            :name="item.icon ?? 'i-lucide-square-check'"
-            class="h-3.5 w-3.5 shrink-0 text-indigo-400"
-          />
-          <span class="truncate">{{ item.title }}</span>
-          <UBadge
-            v-if="item.needsImport"
-            color="neutral"
-            variant="soft"
-            size="xs"
-            class="ms-1 shrink-0"
-          >
-            {{ t('contextAttachments.importsOnAdd') }}
-          </UBadge>
-          <button
-            type="button"
-            class="ms-auto shrink-0 text-slate-400 hover:text-slate-200"
-            @click="removePending(item)"
+          <div class="flex items-center gap-1.5 px-2 py-1.5 text-xs text-slate-300">
+            <UIcon
+              :name="item.icon ?? 'i-lucide-square-check'"
+              class="h-3.5 w-3.5 shrink-0 text-indigo-400"
+            />
+            <span class="truncate">{{ item.title }}</span>
+            <UBadge
+              v-if="item.needsImport"
+              color="neutral"
+              variant="soft"
+              size="xs"
+              class="ms-1 shrink-0"
+            >
+              {{ t('contextAttachments.importsOnAdd') }}
+            </UBadge>
+            <button
+              type="button"
+              class="ms-auto shrink-0 text-slate-400 hover:text-slate-200"
+              @click="removePending(item)"
+            >
+              <UIcon name="i-lucide-x" class="h-3.5 w-3.5" />
+            </button>
+          </div>
+          <!-- An issue reference gets no pre-flight of its own (there is no `parseRef` to ask a
+               tracker), so this line IS its warning: the fetch is attempted when the form opens and
+               again on submit, and a failure now blocks the create. -->
+          <p
+            v-if="item.unreadable"
+            class="px-2 pb-1.5 text-[11px] text-amber-400"
+            data-testid="context-item-unreadable"
           >
-            <UIcon name="i-lucide-x" class="h-3.5 w-3.5" />
-          </button>
+            {{ t('contextAttachments.unreadable', { error: item.unreadable }) }}
+          </p>
         </div>
       </div>
       <p v-else class="text-[11px] text-slate-500">

package/app/components/documents/ContextDocumentPicker.logic.spec.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+import type { ResolvedDocumentRef } from '@cat-factory/contracts'
+import { ApiError } from '~/composables/api/errors'
+import {
+  classifyRefFailure,
+  refCandidateOf,
+  refRowFor,
+  type RefState,
+} from '~/components/documents/ContextDocumentPicker.logic'
+
+// The picker used to stage whatever text sat in its input, so a Figma share link (title segment
+// plus `?p=`/`&t=` params) was accepted verbatim and a link the source could not read at all was
+// accepted just as readily, the verdict arriving as a failed import after the task was created.
+// These three functions are what makes the verdict arrive first, and each is pinned here.
+
+/** The refusal envelope the resolve endpoint answers with, as a thrown `ApiError`. */
+function refusal(details: Record<string, unknown>): ApiError {
+  return new ApiError(422, { error: { code: 'validation', message: 'nope', details } })
+}
+
+describe('refCandidateOf', () => {
+  it('treats any non-empty text as a reference for a source with no catalogue search', () => {
+    // Pasting is the only way to attach a page to such a source, so a bare id must resolve.
+    expect(refCandidateOf('  6k0gqOC6ppDMAziCmZ2Gv9  ', false)).toBe('6k0gqOC6ppDMAziCmZ2Gv9')
+    expect(refCandidateOf('   ', false)).toBeNull()
+  })
+
+  it('leaves a plain search phrase alone on a searchable source', () => {
+    // Resolving every keystroke of a title search would render a refusal at someone who is
+    // simply searching, which is the opposite of the point.
+    expect(refCandidateOf('export requirements', true)).toBeNull()
+    expect(refCandidateOf('https://www.figma.com/design/K/T?node-id=1-2', true)).toBe(
+      'https://www.figma.com/design/K/T?node-id=1-2',
+    )
+    // A link with the scheme pasted off is still a link.
+    expect(refCandidateOf('notion.so/Checkout-PRD-1f2e3d', true)).toBe(
+      'notion.so/Checkout-PRD-1f2e3d',
+    )
+  })
+
+  it('does not read a PHRASE as a reference just because it carries punctuation', () => {
+    // The consequence of a false positive changed with this surface: it used to cost an ignorable
+    // extra row, and now it renders "Not a Notion reference" in amber above the results for that
+    // very phrase. Whitespace is the tell, so `/` and `#` inside a title search no longer qualify.
+    expect(refCandidateOf('auth/login flow', true)).toBeNull()
+    expect(refCandidateOf('sprint #4 plan', true)).toBeNull()
+    expect(refCandidateOf('roadmap Q3/Q4', true)).toBeNull()
+  })
+
+  it('accepts the bare id shapes no title could be confused with', () => {
+    // Worth ASKING about (the backend stays the judge): a Notion id dashed or dashless, and a
+    // Confluence page id. A single unrecognised word is a search, not an id.
+    expect(refCandidateOf('1f2e3d4c5b6a78901234567890abcdef', true)).toBe(
+      '1f2e3d4c5b6a78901234567890abcdef',
+    )
+    expect(refCandidateOf('1f2e3d4c-5b6a-7890-1234-567890abcdef', true)).toBe(
+      '1f2e3d4c-5b6a-7890-1234-567890abcdef',
+    )
+    expect(refCandidateOf('123456', true)).toBe('123456')
+    expect(refCandidateOf('authentication', true)).toBeNull()
+  })
+})
+
+describe('classifyRefFailure', () => {
+  it('reads the two refusal reasons and the detail each correction needs', () => {
+    expect(
+      classifyRefFailure(
+        refusal({ reason: 'document_ref_claimed_by_other_source', claimedBy: 'figma' }),
+      ),
+    ).toEqual({
+      status: 'rejected',
+      reason: 'document_ref_claimed_by_other_source',
+      claimedBy: 'figma',
+    })
+
+    expect(
+      classifyRefFailure(refusal({ reason: 'document_ref_unrecognized', expected: 'https://…' })),
+    ).toEqual({ status: 'rejected', reason: 'document_ref_unrecognized', expected: 'https://…' })
+  })
+
+  it('leaves the reference UNCHECKED when the call failed rather than the source refusing', () => {
+    // A 502, an offline browser or a proxy's own error page says nothing about the link. Reading
+    // any error as a refusal would send the user off to fix a link that was fine.
+    expect(classifyRefFailure(new Error('Failed to fetch'))).toEqual({
+      status: 'unchecked',
+      message: 'Failed to fetch',
+    })
+    expect(classifyRefFailure(new ApiError(502, '<html>bad gateway</html>')).status).toBe(
+      'unchecked',
+    )
+  })
+
+  it('does not trust a reason outside the contract vocabulary', () => {
+    // An older or newer backend can name a reason this build has no copy for; rendering it as a
+    // refusal would show the user a blank explanation for a link that may be perfectly good.
+    expect(classifyRefFailure(refusal({ reason: 'something_new' })).status).toBe('unchecked')
+  })
+})
+
+describe('refRowFor', () => {
+  const resolved = {
+    source: 'figma' as const,
+    externalId: '6k0gqOC6ppDMAziCmZ2Gv9:5765:57229',
+    canonicalUrl: 'https://www.figma.com/design/6k0gqOC6ppDMAziCmZ2Gv9?node-id=5765-57229',
+    droppedScope: null,
+  }
+  const ok = (ref: ResolvedDocumentRef): RefState => ({ status: 'ok', ref })
+
+  it('labels the row with the CANONICAL form and flags that the paste was trimmed', () => {
+    const row = refRowFor(
+      ok(resolved),
+      'https://www.figma.com/design/6k0gqOC6ppDMAziCmZ2Gv9/Project-Redwood--Autopilot-AI-' +
+        '?node-id=5765-57229&p=f&t=J1SrKp6sgJm9CIeQ-0',
+    )
+    expect(row).toEqual({
+      externalId: resolved.externalId,
+      source: 'figma',
+      canonicalUrl: resolved.canonicalUrl,
+      label: resolved.canonicalUrl,
+      trimmed: true,
+      droppedScope: null,
+      unchecked: false,
+    })
+  })
+
+  it('does not claim a trim when the canonical form is what was pasted', () => {
+    expect(refRowFor(ok(resolved), ` ${resolved.canonicalUrl} `)).toMatchObject({ trimmed: false })
+  })
+
+  it('carries a WIDENED reference separately from a trim', () => {
+    // The two are opposite facts wearing the same clothes. A trim resolves the same page; dropping
+    // an unreadable `node-id` swaps one frame for the whole design file, and the label alone cannot
+    // show it (a whole-file canonical URL looks perfectly well-formed). A row that reported only
+    // `trimmed` here is how "I attached this frame" became "the agent read everything".
+    const widened = {
+      source: 'figma' as const,
+      externalId: '6k0gqOC6ppDMAziCmZ2Gv9',
+      canonicalUrl: 'https://www.figma.com/design/6k0gqOC6ppDMAziCmZ2Gv9',
+      droppedScope: 'I2649:14930;2649:14746',
+    }
+    const row = refRowFor(
+      ok(widened),
+      'https://www.figma.com/design/6k0gqOC6ppDMAziCmZ2Gv9/R?node-id=I2649:14930;2649:14746',
+    )
+    expect(row).toMatchObject({ trimmed: true, droppedScope: 'I2649:14930;2649:14746' })
+  })
+
+  it('prefers the imported page title, and falls back to the id when there is no URL to show', () => {
+    expect(refRowFor(ok(resolved), resolved.canonicalUrl, 'Autopilot Home')?.label).toBe(
+      'Autopilot Home',
+    )
+    // A Confluence page id cannot be rendered back as a URL without the site base, so the id
+    // itself is the canonical form, not a missing one.
+    const noUrl = {
+      source: 'confluence' as const,
+      externalId: '4567',
+      canonicalUrl: null,
+      droppedScope: null,
+    }
+    expect(refRowFor(ok(noUrl), '4567')).toMatchObject({ label: '4567', trimmed: false })
+  })
+
+  it('still offers an UNJUDGED reference, carrying the pasted text', () => {
+    // "The source refused this" and "we could not ask" are different facts, and only the first is
+    // evidence against a link. Suppressing the row for the second made a transient 502 or an
+    // offline moment as final as a refusal: attaching a perfectly good link became impossible,
+    // where the import had always been the backstop.
+    const row = refRowFor({ status: 'unchecked', message: 'Failed to fetch' }, ' notion.so/abc ')
+    expect(row).toEqual({
+      externalId: 'notion.so/abc',
+      // Only the resolve answers which source claims a paste; the picker supplies the selected one.
+      source: null,
+      canonicalUrl: null,
+      label: 'notion.so/abc',
+      trimmed: false,
+      droppedScope: null,
+      unchecked: true,
+    })
+  })
+
+  it('offers nothing while checking, or once the source has refused', () => {
+    expect(refRowFor({ status: 'none' }, 'x')).toBeNull()
+    expect(refRowFor({ status: 'checking' }, 'x')).toBeNull()
+    expect(refRowFor({ status: 'rejected', reason: 'document_ref_unrecognized' }, 'x')).toBeNull()
+  })
+})