@cat-factory/app 0.234.2 → 0.236.0

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

@@ -0,0 +1,178 @@
+import {
+  documentRefReasonSchema,
+  type DocumentRefReason,
+  type DocumentSourceKind,
+  type ResolvedDocumentRef,
+} from '@cat-factory/contracts'
+import { apiErrorEnvelope, apiErrorReason } from '~/composables/api/errors'
+
+// The pure half of ContextDocumentPicker: deciding what counts as a pasted REFERENCE rather than a
+// search phrase, reading the backend's verdict on one, and describing the row it becomes.
+// Extracted for the reason every `*.logic.ts` here is (a decision worth a test should not need a
+// mounted component to reach), and these three carry the whole "don't silently accept a bad link"
+// rule the picker exists to enforce.
+
+/** What the picker knows about the reference currently in its input. */
+export type RefState =
+  /** Nothing pasted, or the text reads as a search phrase. */
+  | { status: 'none' }
+  | { status: 'checking' }
+  | { status: 'ok'; ref: ResolvedDocumentRef }
+  /** The SOURCE refused it. `reason` decides which correction the user is offered. */
+  | { status: 'rejected'; reason: DocumentRefReason; claimedBy?: string; expected?: string }
+  /**
+   * The resolve call itself failed (offline, 5xx). The reference is UNJUDGED, not refused, and
+   * saying so matters: a pre-flight outage rendered as "your link is wrong" sends the user off to
+   * fix a link that was fine.
+   */
+  | { status: 'unchecked'; message: string }
+
+/**
+ * The text to resolve as a reference, or null when there is nothing to resolve.
+ *
+ * A source with no catalogue search takes any non-empty text (pasting is the only way to attach a
+ * page there, mirroring the import modal's single input). A searchable one only treats text that
+ * READS as a reference that way, so typing a title does not fire a resolve on every keystroke and
+ * does not render a refusal at someone who is simply searching.
+ */
+export function refCandidateOf(query: string, searchable: boolean): string | null {
+  const trimmed = query.trim()
+  if (!trimmed) return null
+  if (!searchable) return trimmed
+  return looksLikeDocumentRef(trimmed) ? trimmed : null
+}
+
+/** The bare-id forms a document source's ref grammar accepts UNAMBIGUOUSLY, so no phrase matches. */
+const BARE_ID_SHAPES = [
+  /** A Notion page id, dashless. */
+  /^[0-9a-f]{32}$/i,
+  /** A dashed UUID (Notion, Linear). */
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+  /** A Confluence page id. */
+  /^\d{4,}$/,
+]
+
+/**
+ * Whether text typed into a SEARCHABLE source's box is a reference rather than a search phrase.
+ *
+ * Deliberately narrow, because the consequence of a false positive changed. It used to cost an
+ * extra row the user could ignore; now the resolve verdict is RENDERED, so a phrase mistaken for a
+ * reference produces "Not a Notion reference" underneath the search box, in amber, above the
+ * results for that same phrase. `auth/login flow` and `sprint #4 plan` are searches, so the first
+ * rule is that anything containing whitespace is one, whatever punctuation it carries: the old
+ * "contains `/` or `#`" test read both of those as malformed links.
+ *
+ * What remains is a URL (with or without its scheme, which people routinely paste off), or one of
+ * the `BARE_ID_SHAPES` no title could be confused with. A bare id in an unrecognised shape simply
+ * is not offered here, which is the pre-existing behaviour: the backend stays the judge of every
+ * candidate this admits, and this only decides which ones are worth ASKING about.
+ */
+function looksLikeDocumentRef(text: string): boolean {
+  if (/\s/.test(text)) return false
+  if (/^https?:\/\//i.test(text)) return true
+  if (/^[\w-]+(\.[\w-]+)+\/\S/.test(text)) return true
+  return BARE_ID_SHAPES.some((shape) => shape.test(text))
+}
+
+/**
+ * Classify a failed resolve.
+ *
+ * A refusal is only a refusal when the backend NAMED a reason we know: the reason vocabulary is
+ * the closed contract picklist, so an unrecognised value (an older/newer backend, a proxy's own
+ * error page, a network fault) lands as `unchecked`. Guessing "rejected" from the mere presence of
+ * an error is the misattribution this whole surface is meant to avoid: it would tell the user
+ * their link is malformed on the strength of a 502.
+ *
+ * The reason is read through `apiErrorReason`, the one helper that normalises this contract (which
+ * client threw, a non-object `details`, a non-string `reason`); only the two extra details each
+ * correction needs are picked off the envelope here.
+ */
+export function classifyRefFailure(error: unknown): RefState {
+  const reason = apiErrorReason(error)
+  if (!isRefReason(reason)) {
+    return { status: 'unchecked', message: error instanceof Error ? error.message : String(error) }
+  }
+  const details = (apiErrorEnvelope(error)?.details ?? {}) as Record<string, unknown>
+  return {
+    status: 'rejected',
+    reason,
+    ...(typeof details.claimedBy === 'string' ? { claimedBy: details.claimedBy } : {}),
+    ...(typeof details.expected === 'string' ? { expected: details.expected } : {}),
+  }
+}
+
+/** Narrow an unknown `details.reason` to the contract's own picklist, never a bare cast. */
+function isRefReason(value: unknown): value is DocumentRefReason {
+  return (
+    typeof value === 'string' &&
+    (documentRefReasonSchema.options as readonly string[]).includes(value)
+  )
+}
+
+/** How a reference is presented as an attachable row. */
+export interface RefRow {
+  /** The reference to stage: the resolved canonical id, or the pasted text when unjudged. */
+  externalId: string
+  /** The source that claimed it; null when the pre-flight never got a verdict. */
+  source: DocumentSourceKind | null
+  /** The canonical link, when the source can rebuild one from the id alone. */
+  canonicalUrl: string | null
+  /** What the row reads as: the imported page's title when we hold it, else the canonical form. */
+  label: string
+  /** The paste carried NOISE the canonical form drops, so the trim is worth stating explicitly. */
+  trimmed: boolean
+  /**
+   * The frame/screen the paste named that this reference does NOT cover (see the contract's
+   * `droppedScope`). Kept apart from {@link trimmed} because they are opposite facts wearing the
+   * same clothes: a trim resolves the same page, a drop WIDENS one frame to a whole design file.
+   */
+  droppedScope: string | null
+  /** The pre-flight could not reach a verdict. Stageable, with the import as the backstop. */
+  unchecked: boolean
+}
+
+/**
+ * Describe the row a reference becomes, or null when there is nothing to offer.
+ *
+ * The label is the CANONICAL form, never the pasted text: showing what was typed would hide the
+ * one thing worth confirming, which is that a share link's title segment and `?p=`/`&t=` tracking
+ * params are gone and the frame the URL named survived the trim. `trimmed` is what lets the row
+ * say so instead of leaving the change to be noticed, and `droppedScope` is what keeps a widened
+ * reference from hiding behind that same note.
+ *
+ * An UNCHECKED reference still yields a row, carrying the pasted text. "The source refused this"
+ * and "we could not ask" are different facts and only the first is a reason to refuse a paste: a
+ * transient 502 or an offline moment must not make attaching a perfectly good link impossible,
+ * which is what suppressing the row does. The import remains the backstop it always was, so the
+ * worst case is the pre-PR behaviour rather than a dead end.
+ */
+export function refRowFor(state: RefState, pasted: string, importedTitle?: string): RefRow | null {
+  if (state.status === 'ok') {
+    const canonical = state.ref.canonicalUrl ?? state.ref.externalId
+    return {
+      externalId: state.ref.externalId,
+      source: state.ref.source,
+      canonicalUrl: state.ref.canonicalUrl,
+      label: importedTitle ?? canonical,
+      trimmed: canonical !== pasted.trim(),
+      droppedScope: state.ref.droppedScope,
+      unchecked: false,
+    }
+  }
+  if (state.status === 'unchecked') {
+    const text = pasted.trim()
+    if (!text) return null
+    return {
+      externalId: text,
+      // Unknown: only the resolve answers which source claims a paste, and guessing it here is
+      // what would stage a Figma link against the Notion picker's key space.
+      source: null,
+      canonicalUrl: null,
+      label: text,
+      trimmed: false,
+      droppedScope: null,
+      unchecked: true,
+    }
+  }
+  return null
+}

package/app/components/documents/ContextDocumentPicker.vue

@@ -8,7 +8,31 @@
 // collects PendingContext items and links them once the block exists (see
 // useContextLinking). A search hit / pasted ref carries `needsImport: true` so
 // it's fetched + persisted before linking. Mirrors ContextIssuePicker.
-import type { DocumentSearchResult, DocumentSourceKind } from '~/types/domain'
+//
+// A PASTED REF IS RESOLVED BEFORE IT CAN BE STAGED, and that is the point of the ref
+// half of this picker. It used to stage whatever text was in the box, so a share link
+// carrying a title segment and `?p=`/`&t=` tracking params (what Figma's own Copy link
+// button produces) was accepted verbatim, and a link the source could not read at all
+// was accepted just as readily. The verdict arrived as a failed import AFTER the task
+// had been created. The resolve call is the source's own `parseRef`, so what is shown
+// here is what the import will do: the canonical trimmed link when it parses, and one
+// of two named corrections when it does not (see `REF_REJECTIONS`).
+//
+// Two distinctions the row has to keep, because collapsing either one recreates the bug in
+// quieter form. A reference the source could parse only by DROPPING the frame the link named
+// carries that fact separately from the trim (`droppedScope`): both change what was pasted,
+// but one resolves the same page and the other attaches the whole design file. And a resolve
+// call that could not be MADE leaves the reference unjudged rather than refused, still
+// stageable with the import as the backstop, because only the source's own refusal is evidence
+// against a link. An outage that made attaching impossible would be a worse failure than the
+// one the pre-flight fixes.
+import type { DocumentRefReason, DocumentSearchResult, DocumentSourceKind } from '~/types/domain'
+import {
+  classifyRefFailure,
+  refCandidateOf,
+  refRowFor,
+  type RefState,
+} from '~/components/documents/ContextDocumentPicker.logic'
 import EmptyState from '~/components/common/EmptyState.vue'
 import RepoContextDocPicker from '~/components/documents/RepoContextDocPicker.vue'
 
@@ -46,6 +70,45 @@ const results = ref<DocumentSearchResult[]>([])
 const searching = ref(false)
 const searchError = ref<string | null>(null)
 
+// What the ref half of the picker knows about the current query. A refusal carries the backend's
+// machine-readable REASON rather than its prose, because the two reasons ask for different
+// corrections and only one of them is fixable from here (see `REF_REJECTIONS`).
+const refState = ref<RefState>({ status: 'none' })
+// Monotonic token so a slow resolve for an earlier query cannot land on a later one: the
+// input is resolved on every keystroke, so out-of-order responses are the normal case.
+let refSeq = 0
+
+/** A source's display name, for a kind the backend named in a refusal (never a raw slug). */
+function sourceLabel(kind: string): string {
+  return documents.sources.find((s) => s.source === kind)?.label ?? kind
+}
+
+/**
+ * Translated copy per refusal reason, an exhaustive `Record` over the closed union so a reason
+ * added on the backend fails the typecheck here rather than reaching the user as English server
+ * prose. Each message names the correction that reason actually calls for.
+ */
+const REF_REJECTIONS: Record<
+  DocumentRefReason,
+  (input: { claimedBy?: string; expected?: string }) => string
+> = {
+  document_ref_unrecognized: ({ expected }) =>
+    t('documents.picker.refUnrecognized', {
+      source: sourceLabel(source.value ?? ''),
+      expected: expected ?? descriptor.value?.refPlaceholder ?? '',
+    }),
+  document_ref_claimed_by_other_source: ({ claimedBy }) =>
+    t('documents.picker.refOtherSource', {
+      source: sourceLabel(source.value ?? ''),
+      claimed: sourceLabel(claimedBy ?? ''),
+    }),
+}
+
+/** The text to resolve as a reference, or null when there is nothing to resolve. */
+const refCandidate = computed(() =>
+  source.value ? refCandidateOf(query.value, searchable.value) : null,
+)
+
 // Debounced search: free text hits the source; a query that's clearly a URL/ID
 // is left to the explicit "by reference" row below (search won't surface it).
 let timer: ReturnType<typeof setTimeout> | undefined
@@ -53,9 +116,14 @@ watch([query, source], () => {
   if (timer) clearTimeout(timer)
   results.value = []
   searchError.value = null
+  refState.value = { status: 'none' }
+  refSeq++
   const q = query.value.trim()
-  if (!q || !searchable.value) return
-  timer = setTimeout(runSearch, 300)
+  if (!q) return
+  timer = setTimeout(() => {
+    if (searchable.value) void runSearch()
+    if (refCandidate.value) void resolveRef(refCandidate.value)
+  }, 300)
 })
 
 async function runSearch() {
@@ -73,6 +141,26 @@ async function runSearch() {
   }
 }
 
+/**
+ * Ask the backend what this text resolves to for the selected source. A 422 is the source's
+ * own refusal and lands as `rejected` with its reason; anything else (offline, 5xx) leaves
+ * the ref UNCHECKED rather than refused, so an outage in the pre-flight never reads to the
+ * user as "your link is wrong".
+ */
+async function resolveRef(candidate: string) {
+  const src = source.value
+  if (!src) return
+  const seq = ++refSeq
+  refState.value = { status: 'checking' }
+  try {
+    const ref = await documents.resolveRef(src, candidate)
+    if (seq === refSeq) refState.value = { status: 'ok', ref }
+  } catch (e) {
+    if (seq !== refSeq) return
+    refState.value = classifyRefFailure(e)
+  }
+}
+
 const icon = computed(() => descriptor.value?.icon ?? 'i-lucide-file-text')
 
 function keyFor(externalId: string): string {
@@ -103,30 +191,96 @@ const searchRows = computed(() => {
     .filter((r) => !chosen.value.has(keyFor(r.externalId)))
 })
 
-// A pasted URL / ID the search won't match: offer it as an explicit reference.
-// When the source isn't searchable, any non-empty query is treated as a ref (the
-// only way to attach a page there, mirroring the import modal's single input).
+/** The already-imported document a resolved ref points at, when the workspace holds it. */
+const refImported = computed(() => {
+  const state = refState.value
+  if (state.status !== 'ok') return undefined
+  return documents.documents.find(
+    (d) => d.source === state.ref.source && d.externalId === state.ref.externalId,
+  )
+})
+
+/** Every id another row in this dropdown already offers, so one page is never listed twice. */
+const offeredIds = computed(
+  () =>
+    new Set([
+      ...importedRows.value.map((d) => d.externalId),
+      ...searchRows.value.map((r) => r.externalId),
+    ]),
+)
+
+/**
+ * The attachable row for the reference in the box: the CANONICAL form the source settled on, never
+ * the text that was typed (see `refRowFor`, which also carries the unjudged case).
+ *
+ * Suppressed in two cases, each with its own reason. Already STAGED, keyed on the resolved external
+ * id so pasting the share link and then the bare id cannot stage it twice (the `refAlreadyAttached`
+ * line says so, since a row that silently vanishes reads as a picker that lost the paste). Already
+ * OFFERED by an imported/search row above, which is the same page reachable by one click: the
+ * dedupe is against what is VISIBLE rather than against the whole imported list, because a URL
+ * query matches no title, so testing the full list would suppress the only row on offer.
+ */
 const refRow = computed(() => {
-  const q = query.value.trim()
-  if (!q || !source.value) return null
-  const known =
-    importedRows.value.some((d) => d.externalId === q) ||
-    searchRows.value.some((r) => r.externalId === q) ||
-    chosen.value.has(keyFor(q))
-  if (known) return null
-  if (!searchable.value) return q
-  // Only worth offering when it looks like a reference, not a search phrase.
-  const looksLikeRef = q.includes('#') || q.includes('/') || /^https?:\/\//i.test(q)
-  return looksLikeRef ? q : null
+  const pasted = refCandidate.value
+  if (!pasted) return null
+  const row = refRowFor(refState.value, pasted, refImported.value?.title)
+  if (!row) return null
+  if (chosen.value.has(keyFor(row.externalId)) || offeredIds.value.has(row.externalId)) return null
+  return { ...row, imported: !!refImported.value }
+})
+
+/** A resolved reference the caller has already staged: suppressed as a row, stated as a line. */
+const refAlreadyAttached = computed(() => {
+  const state = refState.value
+  return state.status === 'ok' && chosen.value.has(keyFor(state.ref.externalId))
 })
 
+/** The refusal to render under the input, in the reader's language, or null. */
+const refRejection = computed(() => {
+  const state = refState.value
+  if (state.status !== 'rejected') return null
+  return REF_REJECTIONS[state.reason]({
+    ...(state.claimedBy ? { claimedBy: state.claimedBy } : {}),
+    ...(state.expected ? { expected: state.expected } : {}),
+  })
+})
+
+/**
+ * The source named by a `claimed_by_other_source` refusal, when it is one this workspace has
+ * connected. Absent when it is not: offering to switch to a source the picker cannot select
+ * would be a dead end, and the refusal copy alone already names what the link is.
+ */
+const refSwitchTarget = computed(() => {
+  const state = refState.value
+  if (state.status !== 'rejected' || !state.claimedBy) return undefined
+  return documents.connectedSources.find((s) => s.source === state.claimedBy)
+})
+
+function switchToClaimingSource() {
+  const target = refSwitchTarget.value
+  if (target) source.value = target.source
+}
+
+/**
+ * Whether a line about the pasted reference is being rendered under the input. It is what keeps the
+ * dropdown TOTAL: every state now shows a row, a line, or the empty state. Keying the empty state
+ * on `status === 'none'` alone left a hole (a resolved reference the caller had already staged
+ * suppressed the row AND the empty state) that rendered as a blank panel explaining nothing.
+ */
+const refNotice = computed(
+  () =>
+    refState.value.status !== 'none' &&
+    (refState.value.status !== 'ok' || refAlreadyAttached.value),
+)
+
 const empty = computed(
   () =>
     !searching.value &&
     !searchError.value &&
     importedRows.value.length === 0 &&
     searchRows.value.length === 0 &&
-    refRow.value === null,
+    refRow.value === null &&
+    !refNotice.value,
 )
 
 function pickImported(externalId: string, title: string, excerpt: string) {
@@ -154,16 +308,26 @@ function pickSearch(r: DocumentSearchResult) {
   })
 }
 
-function pickRef(q: string) {
-  if (!source.value) return
+/**
+ * Stage a reference. The canonical external id is staged, never the pasted text, so the item the
+ * host commits is the one the pre-flight judged. A reference the workspace has already imported
+ * skips the re-fetch (`needsImport: false`) and carries its real title.
+ *
+ * An UNJUDGED reference (the resolve call itself failed) carries the pasted text against the
+ * SELECTED source, which is what the picker did before any pre-flight existed: the import will
+ * judge it, and a source outage is not a reason to make attaching impossible.
+ */
+function pickRef(row: NonNullable<typeof refRow.value>) {
+  const src = row.source ?? source.value
+  if (!src) return
   emit('pick', {
     kind: 'document',
-    source: source.value,
-    externalId: q,
-    title: q,
-    subtitle: descriptor.value?.label,
+    source: src,
+    externalId: row.externalId,
+    title: row.label,
+    subtitle: row.canonicalUrl ?? descriptor.value?.label,
     icon: icon.value,
-    needsImport: true,
+    needsImport: !row.imported,
   })
   query.value = ''
 }
@@ -212,6 +376,50 @@ onMounted(() => {
         {{ t('documents.picker.searchFailed', { error: searchError }) }}
       </p>
 
+      <!-- The pre-flight's verdict on a pasted ref. A refusal is stated HERE, under the input
+           the user can still edit, rather than as a toast after the task is created. -->
+      <p
+        v-if="refState.status === 'checking'"
+        class="px-1 text-[11px] text-slate-500"
+        data-testid="doc-ref-checking"
+      >
+        {{ t('documents.picker.refChecking') }}
+      </p>
+      <div
+        v-else-if="refRejection"
+        class="flex flex-wrap items-center gap-x-2 gap-y-1 px-1 text-[11px] text-amber-400"
+        data-testid="doc-ref-rejected"
+      >
+        <span>{{ refRejection }}</span>
+        <UButton
+          v-if="refSwitchTarget"
+          color="neutral"
+          variant="link"
+          size="xs"
+          class="p-0"
+          data-testid="doc-ref-switch-source"
+          @click="switchToClaimingSource"
+        >
+          {{ t('documents.picker.refSwitchSource', { source: refSwitchTarget.label }) }}
+        </UButton>
+      </div>
+      <p
+        v-else-if="refState.status === 'unchecked'"
+        class="px-1 text-[11px] text-amber-400"
+        data-testid="doc-ref-unchecked"
+      >
+        {{ t('documents.picker.refCheckFailed', { error: refState.message }) }}
+      </p>
+      <!-- Already staged, so the row is suppressed. Stated, because a paste that produces nothing
+           at all reads as a picker that dropped it. -->
+      <p
+        v-else-if="refAlreadyAttached"
+        class="px-1 text-[11px] text-slate-500"
+        data-testid="doc-ref-already-attached"
+      >
+        {{ t('documents.picker.refAlreadyAttached') }}
+      </p>
+
       <div class="max-h-56 space-y-0.5 overflow-y-auto">
         <!-- Already-imported documents (linked directly, no re-fetch). -->
         <button
@@ -240,21 +448,48 @@ onMounted(() => {
           <span class="truncate">{{ r.title }}</span>
         </button>
 
-        <!-- Explicit URL/ID reference (imported on add). -->
+        <!-- Explicit URL/ID reference, RESOLVED: the row shows the canonical form the source
+             settled on, so a share link's title segment and tracking params are visibly gone
+             before the attachment is staged. -->
         <button
           v-if="refRow"
           type="button"
-          class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-start text-xs text-slate-300 hover:bg-slate-800/70"
+          class="flex w-full items-start gap-1.5 rounded-md px-2 py-1.5 text-start text-xs text-slate-300 hover:bg-slate-800/70"
+          data-testid="doc-ref-attach"
           @click="pickRef(refRow)"
         >
-          <UIcon name="i-lucide-link" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
-          <span class="truncate">
-            <i18n-t keypath="documents.picker.attachByReference" scope="global">
-              <template #ref>
-                <span class="text-slate-200">{{ refRow }}</span>
-              </template>
-            </i18n-t>
+          <UIcon name="i-lucide-link" class="mt-0.5 h-3.5 w-3.5 shrink-0 text-slate-400" />
+          <span class="min-w-0">
+            <span class="block truncate">
+              <i18n-t keypath="documents.picker.attachByReference" scope="global">
+                <template #ref>
+                  <span class="text-slate-200">{{ refRow.label }}</span>
+                </template>
+              </i18n-t>
+            </span>
+            <span v-if="refRow.trimmed" class="block truncate text-[11px] text-slate-500">
+              {{ t('documents.picker.refTrimmed') }}
+            </span>
+            <!-- A WIDENED reference, which the trim note above must never be left to imply: the
+                 frame this link named could not be read, so what gets attached is everything
+                 around it. Amber and separate, because it is a loss rather than tidying. -->
+            <span
+              v-if="refRow.droppedScope"
+              class="block text-[11px] text-amber-400"
+              data-testid="doc-ref-widened"
+            >
+              {{ t('documents.picker.refWidened', { scope: refRow.droppedScope }) }}
+            </span>
           </span>
+          <UBadge
+            v-if="refRow.imported"
+            color="neutral"
+            variant="soft"
+            size="xs"
+            class="ms-auto shrink-0"
+          >
+            {{ t('documents.picker.importedBadge') }}
+          </UBadge>
         </button>
 
         <EmptyState

package/app/components/pipeline/AgentKindIcon.vue

@@ -2,7 +2,7 @@
 // The single rendering path for an agent kind's icon (+ optional label) anywhere a
 // pipeline or run lists its steps. Resolves display metadata through
 // `agentKindMeta`, which is total over every kind — palette archetypes, custom
-// agents and the engine's system kinds (ci / merger / blueprints / conflicts) — so
+// agents and the engine's system kinds (ci / merger / conflicts) — so
 // a saved pipeline that contains a system kind can never blow up the renderer.
 import { computed } from 'vue'
 import { agentKindMeta } from '~/utils/catalog'

package/app/components/settings/ModelConfigurationPanel.vue

@@ -56,8 +56,8 @@ const busy = ref(false)
 const filter = ref('')
 
 // The palette archetypes PLUS the engine-driven kinds that still run an LLM
-// (spec-writer, merger, the fixers/resolver). The pure gates run no model, so they
-// stay out — exactly the set the per-agent override list should cover.
+// (merger, the fixers/resolver). The pure gates run no model, so they stay out —
+// exactly the set the per-agent override list should cover.
 const configurableKinds = computed(() => [...agents.archetypes, ...MODEL_CONFIGURABLE_SYSTEM_KINDS])
 
 // Narrowed to the selected agent tier, EXCEPT that a kind the preset being edited already

package/app/composables/api/documents.ts

@@ -9,6 +9,7 @@ import {
   listDocumentsContract,
   listDocumentSourcesContract,
   planDocumentContract,
+  resolveDocumentRefContract,
   searchDocumentsContract,
   spawnDocumentContract,
   unlinkDocumentForKindContract,
@@ -48,6 +49,15 @@ export function documentsApi({ send, ws }: ApiContext) {
     listDocuments: (workspaceId: string) =>
       send(listDocumentsContract, { pathPrefix: ws(workspaceId) }),
 
+    // Canonicalise a pasted URL/id without importing it: the pre-flight the attach pickers run
+    // so an unusable link is corrected before the task that carries it is saved.
+    resolveDocumentRef: (workspaceId: string, source: DocumentSourceKind, body: { ref: string }) =>
+      send(resolveDocumentRefContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
+        body,
+      }),
+
     importDocument: (workspaceId: string, source: DocumentSourceKind, body: { ref: string }) =>
       send(importDocumentContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),