@cat-factory/app 0.13.0 → 0.15.0

package/app/components/board/AddTaskModal.vue

@@ -12,6 +12,7 @@
 // (see useContextLinking) — the same context the agents see for every step of the run.
 import type { DropdownMenuItem } from '@nuxt/ui'
 import type { CreateTaskType, TaskTypeFields } from '~/types/domain'
+import ContextIssuePicker from '~/components/tasks/ContextIssuePicker.vue'
 
 const ui = useUiStore()
 const board = useBoardStore()
@@ -230,32 +231,12 @@ const docAttachMenu = computed<DropdownMenuItem[][]>(() => {
   return [items]
 })
 
-const issueAttachMenu = computed<DropdownMenuItem[][]>(() => {
-  const chosen = new Set(pendingContext.value.map(contextKey))
-  const items: DropdownMenuItem[] = tasks.tasks
-    .filter(
-      (t) => !chosen.has(contextKey({ kind: 'task', source: t.source, externalId: t.externalId })),
-    )
-    .map((t) => ({
-      label: `${t.externalId} · ${t.title}`,
-      icon: tasks.descriptorFor(t.source)?.icon ?? 'i-lucide-square-check',
-      onSelect: () =>
-        addPending({
-          kind: 'task',
-          source: t.source,
-          externalId: t.externalId,
-          title: `${t.externalId} · ${t.title}`,
-          icon: tasks.descriptorFor(t.source)?.icon ?? 'i-lucide-square-check',
-          needsImport: false,
-        }),
-    }))
-  items.push({
-    label: 'Import an issue…',
-    icon: 'i-lucide-file-down',
-    onSelect: () => ui.openTaskImport(),
-  })
-  return [items]
-})
+// Context issues are picked through an inline search picker (ContextIssuePicker)
+// rather than a dropdown that opens a second modal — stacked page-level modals
+// don't interact here, which is why the old "Import an issue…" path appeared to
+// do nothing. The "Attach" button toggles the picker open.
+const showIssuePicker = ref(false)
+const chosenIssueKeys = computed(() => pendingIssues.value.map(contextKey))
 
 // Reset the form whenever the modal opens for a (new) container, and refresh the
 // imported docs/issues so the quick-pick list is current.
@@ -274,6 +255,7 @@ watch(open, (isOpen) => {
   pipelineId.value = ''
   agentConfigValues.value = {}
   pendingContext.value = []
+  showIssuePicker.value = false
   documents.loadDocuments().catch(() => {})
   tasks.loadTasks().catch(() => {})
 })
@@ -591,15 +573,16 @@ async function add() {
               <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
                 Context issues
               </span>
-              <UDropdownMenu
+              <UButton
                 v-if="issuesConnected"
-                :items="issueAttachMenu"
-                :content="{ side: 'bottom', align: 'end' }"
+                color="neutral"
+                variant="soft"
+                size="xs"
+                :icon="showIssuePicker ? 'i-lucide-x' : 'i-lucide-plus'"
+                @click="showIssuePicker = !showIssuePicker"
               >
-                <UButton color="neutral" variant="soft" size="xs" icon="i-lucide-plus">
-                  Attach
-                </UButton>
-              </UDropdownMenu>
+                {{ showIssuePicker ? 'Done' : 'Attach' }}
+              </UButton>
               <UButton
                 v-else
                 color="neutral"
@@ -616,6 +599,11 @@ async function add() {
                 Attach
               </UButton>
             </div>
+            <ContextIssuePicker
+              v-if="showIssuePicker && issuesConnected"
+              :chosen-keys="chosenIssueKeys"
+              @pick="addPending"
+            />
             <div v-if="pendingIssues.length" class="space-y-1">
               <div
                 v-for="item in pendingIssues"

package/app/components/layout/IntegrationsHub.vue

@@ -12,8 +12,16 @@ const github = useGitHubStore()
 const slack = useSlackStore()
 const documents = useDocumentsStore()
 const tasks = useTasksStore()
+const tracker = useTrackerStore()
 const releaseHealth = useReleaseHealthStore()
 
+// The selected filing tracker, as a badge label ("GitHub Issues" / "Jira").
+const trackerLabel = computed(() => {
+  if (tracker.settings.tracker === 'github') return 'GitHub Issues'
+  if (tracker.settings.tracker === 'jira') return 'Jira'
+  return undefined
+})
+
 // The observability connection status drives the hub's connected badge. Load it
 // lazily when the hub opens (the secret-less connection view is cheap).
 watch(
@@ -130,11 +138,13 @@ const groups = computed<IntegrationGroup[]>(() => {
       })
     }
     trackers.push({
-      key: 'task:writeback',
-      icon: 'i-lucide-message-square-reply',
-      label: 'Issue tracker writeback',
-      description: 'Comment on the PR and close the linked issue on merge.',
-      onClick: () => go(() => ui.openWorkspaceSettings('writeback')),
+      key: 'task:tracker',
+      icon: 'i-lucide-list-checks',
+      label: 'Issue tracker settings',
+      description: 'Choose the filing tracker, enable linking sources, and configure writeback.',
+      status: trackerLabel.value,
+      connected: tracker.settings.tracker !== null,
+      onClick: () => go(() => ui.openWorkspaceSettings('tracker')),
     })
     out.push({ title: 'Task trackers', items: trackers })
   }

package/app/components/settings/IssueTrackerPanel.vue

@@ -0,0 +1,393 @@
+<script setup lang="ts">
+// Workspace settings: a single, first-class home for issue tracking. It gathers
+// the three things that used to be scattered (and, for the filing tracker, were
+// only reachable buried inside the tech-debt recurring-pipeline modal):
+//
+//   1. Filing tracker — which tracker the tech-debt pipeline's `tracker` step
+//      files its ticket in (GitHub Issues / Jira / none).
+//   2. Linking sources — the per-workspace on/off toggle for each source
+//      (task_source_settings) that governs whether issues can be imported and
+//      linked to tasks as agent context.
+//   3. Writeback — comment on a task's linked issue when its PR opens, and
+//      comment + close it when the PR merges.
+//
+// Filing and linking are independent (filing rides the App / Jira connection
+// directly; linking is the source toggle), so both are shown explicitly to undo
+// the common confusion that "I have the GitHub App, why is nothing surfaced?".
+import { computed, onMounted, ref, watch } from 'vue'
+import type { TaskSourceDiagnosticStatus, TaskSourceKind, TrackerKind } from '~/types/domain'
+
+const tracker = useTrackerStore()
+const tasks = useTasksStore()
+const ui = useUiStore()
+const toast = useToast()
+
+// --- filing tracker + writeback (one Save, persisted on tracker settings) -----
+const trackerKind = ref<TrackerKind | null>(null)
+const jiraProjectKey = ref('')
+const commentOnPrOpen = ref(false)
+const resolveOnMerge = ref(false)
+const saving = ref(false)
+
+function hydrate() {
+  trackerKind.value = tracker.settings.tracker
+  jiraProjectKey.value = tracker.settings.jiraProjectKey ?? ''
+  commentOnPrOpen.value = tracker.settings.writebackCommentOnPrOpen
+  resolveOnMerge.value = tracker.settings.writebackResolveOnMerge
+}
+onMounted(() => {
+  hydrate()
+  // The descriptors (availability + enable state) come from the task-source probe;
+  // probe on open if the navbar hasn't already, so the toggles below reflect reality.
+  if (tasks.available === null) void tasks.probe()
+})
+watch(() => tracker.settings, hydrate, { deep: true })
+
+// Per-source live state (available = usable now; enabled = offered to the workspace).
+const github = computed(() => tasks.descriptorFor('github'))
+const jira = computed(() => tasks.descriptorFor('jira'))
+
+// A tracker can only file where it can authenticate: GitHub rides the installed
+// App, Jira needs a connection. Selecting an unusable tracker is allowed (it just
+// won't file until set up), but we surface the gap inline.
+const githubAvailable = computed(() => github.value?.available ?? false)
+const jiraConnected = computed(() => tasks.isConnected('jira'))
+
+// Jira needs a project key to file into; block Save on an empty one when picked.
+const canSave = computed(
+  () => trackerKind.value !== 'jira' || jiraProjectKey.value.trim().length > 0,
+)
+
+async function save() {
+  if (!canSave.value) return
+  saving.value = true
+  try {
+    await tracker.save({
+      tracker: trackerKind.value,
+      jiraProjectKey: trackerKind.value === 'jira' ? jiraProjectKey.value.trim() : null,
+      writebackCommentOnPrOpen: commentOnPrOpen.value,
+      writebackResolveOnMerge: resolveOnMerge.value,
+    })
+    toast.add({ title: 'Issue tracker saved', icon: 'i-lucide-check', color: 'success' })
+  } catch (e) {
+    toast.add({
+      title: 'Could not save settings',
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    saving.value = false
+  }
+}
+
+// --- linking sources (per-source toggle, saved immediately) -------------------
+const togglingSource = ref<TaskSourceKind | null>(null)
+
+async function toggleSource(source: TaskSourceKind, enabled: boolean) {
+  togglingSource.value = source
+  try {
+    await tasks.setEnabled(source, enabled)
+  } catch (e) {
+    toast.add({
+      title: 'Could not update',
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    togglingSource.value = null
+  }
+}
+
+// --- live "check setup" -------------------------------------------------------
+// The probe failed entirely (not a per-source state): the whole integration is
+// off or the backend errored, so the panel can't show real source state. We
+// translate the captured status into a plain explanation + next step.
+const probeFailureHint = computed(() => {
+  const err = tasks.probeError
+  if (tasks.available !== false || !err) return null
+  if (err.status === 503) {
+    return 'The task-source integration is turned off on this deployment (its encryption key is not configured). Set ENCRYPTION_KEY on the backend to enable issue tracking.'
+  }
+  if (err.status && err.status >= 500) {
+    return `The issue-tracker service returned an error (HTTP ${err.status}): ${err.message}. This usually means the backend isn't fully migrated/configured.`
+  }
+  return `Couldn't load issue-tracker settings${err.status ? ` (HTTP ${err.status})` : ''}: ${err.message}`
+})
+
+async function checkSetup(source: TaskSourceKind) {
+  try {
+    await tasks.checkSetup(source)
+  } catch (e) {
+    toast.add({
+      title: 'Check failed',
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  }
+}
+
+// Status → presentation for a setup-check verdict.
+const STATUS_UI: Record<
+  TaskSourceDiagnosticStatus,
+  { color: 'success' | 'warning' | 'error' | 'neutral'; icon: string }
+> = {
+  ready: { color: 'success', icon: 'i-lucide-circle-check' },
+  not_installed: { color: 'warning', icon: 'i-lucide-download' },
+  not_connected: { color: 'warning', icon: 'i-lucide-plug' },
+  auth_failed: { color: 'error', icon: 'i-lucide-key-round' },
+  forbidden: { color: 'error', icon: 'i-lucide-shield-x' },
+  unreachable: { color: 'error', icon: 'i-lucide-wifi-off' },
+  error: { color: 'error', icon: 'i-lucide-triangle-alert' },
+}
+</script>
+
+<template>
+  <div class="space-y-7">
+    <!-- Whole-integration failure: explain WHY nothing is surfaced, instead of the
+         passive per-source "install first" hints (which would be misleading here). -->
+    <UAlert
+      v-if="probeFailureHint"
+      color="error"
+      variant="subtle"
+      icon="i-lucide-triangle-alert"
+      title="Issue tracking isn't available"
+      :description="probeFailureHint"
+    />
+
+    <!-- 1. Filing tracker ----------------------------------------------------->
+    <section class="space-y-3">
+      <div>
+        <h3 class="text-sm font-semibold text-slate-200">Where tickets are filed</h3>
+        <p class="mt-1 text-[11px] text-slate-400">
+          The tech-debt recurring pipeline raises an issue before implementation and files it in
+          this tracker. Choose <span class="text-slate-300">None</span> to skip filing.
+        </p>
+      </div>
+
+      <div class="flex flex-wrap gap-2">
+        <UButton
+          icon="i-lucide-circle-slash"
+          size="sm"
+          :color="trackerKind === null ? 'primary' : 'neutral'"
+          :variant="trackerKind === null ? 'solid' : 'subtle'"
+          @click="trackerKind = null"
+        >
+          None
+        </UButton>
+        <UButton
+          icon="i-lucide-github"
+          size="sm"
+          :color="trackerKind === 'github' ? 'primary' : 'neutral'"
+          :variant="trackerKind === 'github' ? 'solid' : 'subtle'"
+          @click="trackerKind = 'github'"
+        >
+          GitHub Issues
+        </UButton>
+        <UButton
+          icon="i-lucide-trello"
+          size="sm"
+          :color="trackerKind === 'jira' ? 'primary' : 'neutral'"
+          :variant="trackerKind === 'jira' ? 'solid' : 'subtle'"
+          @click="trackerKind = 'jira'"
+        >
+          Jira
+        </UButton>
+      </div>
+
+      <!-- Inline readiness hints for the picked tracker. -->
+      <p v-if="trackerKind === 'github' && !githubAvailable" class="text-[11px] text-amber-400">
+        GitHub Issues rides your installed GitHub App, which isn't connected yet. Install it under
+        <button class="underline" @click="ui.openGitHub()">Integrations → GitHub</button> — filing
+        stays off until then.
+      </p>
+      <p v-else-if="trackerKind === 'jira' && !jiraConnected" class="text-[11px] text-amber-400">
+        Jira isn't connected yet.
+        <button class="underline" @click="ui.openTaskConnect('jira')">Connect it</button> to file
+        and link issues.
+      </p>
+
+      <UFormField v-if="trackerKind === 'jira'" label="Jira project key" class="w-48">
+        <UInput v-model="jiraProjectKey" placeholder="ENG" size="sm" class="w-full" />
+        <template #help>
+          <span class="text-[11px] text-slate-500">New tickets are filed under this project.</span>
+        </template>
+      </UFormField>
+    </section>
+
+    <!-- 2. Linking sources ---------------------------------------------------->
+    <section class="space-y-3">
+      <div>
+        <h3 class="text-sm font-semibold text-slate-200">Link issues as context</h3>
+        <p class="mt-1 text-[11px] text-slate-400">
+          When a source is offered you can import its issues and attach them to a task, so agents
+          see the issue description and comments while implementing. This is independent of the
+          filing tracker above.
+        </p>
+      </div>
+
+      <!-- GitHub Issues source -->
+      <div class="rounded-lg border border-slate-800 bg-slate-800/40 px-3 py-2.5">
+        <div class="flex items-center justify-between gap-2">
+          <div class="flex min-w-0 items-center gap-2.5">
+            <UIcon name="i-lucide-github" class="h-5 w-5 shrink-0 text-slate-300" />
+            <div class="min-w-0">
+              <div class="text-sm font-medium text-slate-200">GitHub Issues</div>
+              <div class="text-[11px] text-slate-500">
+                {{
+                  githubAvailable
+                    ? 'Rides your installed GitHub App — no credentials needed.'
+                    : 'Install the GitHub App (Integrations → GitHub) to offer this source.'
+                }}
+              </div>
+            </div>
+          </div>
+          <div class="flex shrink-0 items-center gap-2">
+            <UButton
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              icon="i-lucide-stethoscope"
+              :loading="tasks.checking === 'github'"
+              @click="checkSetup('github')"
+            >
+              Check setup
+            </UButton>
+            <USwitch
+              v-if="githubAvailable"
+              :model-value="github?.enabled ?? false"
+              :loading="togglingSource === 'github'"
+              @update:model-value="(v: boolean) => toggleSource('github', v)"
+            />
+            <UButton
+              v-else
+              size="xs"
+              color="neutral"
+              variant="soft"
+              icon="i-lucide-github"
+              @click="ui.openGitHub()"
+            >
+              Install
+            </UButton>
+          </div>
+        </div>
+        <UAlert
+          v-if="tasks.diagnostics.github"
+          class="mt-2.5"
+          :color="STATUS_UI[tasks.diagnostics.github.status].color"
+          variant="subtle"
+          :icon="STATUS_UI[tasks.diagnostics.github.status].icon"
+          :description="
+            tasks.diagnostics.github.message +
+            (tasks.diagnostics.github.detail ? ` ${tasks.diagnostics.github.detail}` : '')
+          "
+          :ui="{ description: 'text-[11px]' }"
+        />
+      </div>
+
+      <!-- Jira source -->
+      <div class="rounded-lg border border-slate-800 bg-slate-800/40 px-3 py-2.5">
+        <div class="flex items-center justify-between gap-2">
+          <div class="flex min-w-0 items-center gap-2.5">
+            <UIcon name="i-lucide-trello" class="h-5 w-5 shrink-0 text-slate-300" />
+            <div class="min-w-0">
+              <div class="text-sm font-medium text-slate-200">Jira</div>
+              <div class="text-[11px] text-slate-500">
+                {{ jiraConnected ? 'Connected.' : 'Connect with a Jira account and API token.' }}
+              </div>
+            </div>
+          </div>
+          <div class="flex shrink-0 items-center gap-2">
+            <UButton
+              v-if="jiraConnected"
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              icon="i-lucide-stethoscope"
+              :loading="tasks.checking === 'jira'"
+              @click="checkSetup('jira')"
+            >
+              Check setup
+            </UButton>
+            <USwitch
+              v-if="jira?.available"
+              :model-value="jira?.enabled ?? false"
+              :loading="togglingSource === 'jira'"
+              @update:model-value="(v: boolean) => toggleSource('jira', v)"
+            />
+            <UButton
+              v-else
+              size="xs"
+              color="neutral"
+              variant="soft"
+              icon="i-lucide-plug"
+              @click="ui.openTaskConnect('jira')"
+            >
+              Connect
+            </UButton>
+          </div>
+        </div>
+        <UAlert
+          v-if="tasks.diagnostics.jira"
+          class="mt-2.5"
+          :color="STATUS_UI[tasks.diagnostics.jira.status].color"
+          variant="subtle"
+          :icon="STATUS_UI[tasks.diagnostics.jira.status].icon"
+          :description="
+            tasks.diagnostics.jira.message +
+            (tasks.diagnostics.jira.detail ? ` ${tasks.diagnostics.jira.detail}` : '')
+          "
+          :ui="{ description: 'text-[11px]' }"
+        />
+      </div>
+    </section>
+
+    <!-- 3. Writeback ---------------------------------------------------------->
+    <section class="space-y-3">
+      <div>
+        <h3 class="text-sm font-semibold text-slate-200">Writeback</h3>
+        <p class="mt-1 text-[11px] text-slate-400">
+          Write back to a task's linked issue(s) as its pull request progresses. Each toggle is the
+          workspace default and can be overridden per task in the inspector. GitHub issues close
+          natively; Jira issues transition to the first status in their
+          <span class="text-slate-300">Done</span> category.
+        </p>
+      </div>
+
+      <label class="flex items-start gap-3 rounded-lg border border-slate-700 bg-slate-800/40 p-3">
+        <USwitch v-model="commentOnPrOpen" />
+        <span class="text-sm">
+          <span class="block text-slate-200">Comment when a PR opens</span>
+          <span class="block text-xs text-slate-500">
+            Post a comment on the linked issue with the new pull request's link.
+          </span>
+        </span>
+      </label>
+
+      <label class="flex items-start gap-3 rounded-lg border border-slate-700 bg-slate-800/40 p-3">
+        <USwitch v-model="resolveOnMerge" />
+        <span class="text-sm">
+          <span class="block text-slate-200">Close as resolved when a PR merges</span>
+          <span class="block text-xs text-slate-500">
+            Comment that the PR merged, then close / resolve the linked issue.
+          </span>
+        </span>
+      </label>
+    </section>
+
+    <div class="flex justify-end">
+      <UButton
+        color="primary"
+        icon="i-lucide-save"
+        size="sm"
+        :loading="saving"
+        :disabled="!canSave"
+        @click="save"
+      >
+        Save
+      </UButton>
+    </div>
+  </div>
+</template>

package/app/components/settings/WorkspaceSettingsPanel.vue

@@ -3,14 +3,14 @@
 // configuration that used to live in separate windows:
 //   - Workspace: the run-timing escalation threshold + per-service running-task limit.
 //   - Merge thresholds: the auto-merge preset library.
-//   - Issue writeback: the tracker writeback toggles.
+//   - Issue tracker: filing-tracker selection + linking sources + writeback.
 //   - Service best practices: the default fragments new services inherit.
 // The latter three are body-only section components rendered in tabs here (no longer
 // standalone modals).
 import { reactive, ref, watch } from 'vue'
 import type { CreateTaskType, TaskLimitMode } from '~/types/domain'
 import MergeThresholdsPanel from '~/components/settings/MergeThresholdsPanel.vue'
-import IssueTrackerWritebackPanel from '~/components/settings/IssueTrackerWritebackPanel.vue'
+import IssueTrackerPanel from '~/components/settings/IssueTrackerPanel.vue'
 import ServiceFragmentDefaultsPanel from '~/components/settings/ServiceFragmentDefaultsPanel.vue'
 
 const ui = useUiStore()
@@ -38,10 +38,10 @@ const tabs = [
   },
   { value: 'merge', label: 'Merge thresholds', icon: 'i-lucide-git-merge', slot: 'merge' },
   {
-    value: 'writeback',
-    label: 'Issue writeback',
-    icon: 'i-lucide-message-square-reply',
-    slot: 'writeback',
+    value: 'tracker',
+    label: 'Issue tracker',
+    icon: 'i-lucide-list-checks',
+    slot: 'tracker',
   },
   {
     value: 'fragments',
@@ -200,9 +200,9 @@ async function save() {
           <MergeThresholdsPanel />
         </template>
 
-        <!-- Issue writeback -->
-        <template #writeback>
-          <IssueTrackerWritebackPanel />
+        <!-- Issue tracker -->
+        <template #tracker>
+          <IssueTrackerPanel />
         </template>
 
         <!-- Service best practices -->

package/app/components/tasks/ContextIssuePicker.vue

@@ -0,0 +1,243 @@
+<script setup lang="ts">
+// Inline picker for attaching a tracker issue as task context. It searches the
+// connected tracker (GitHub Issues / Jira) by free text, lists already-imported
+// issues for quick re-use, and accepts a pasted URL/key as a reference — all
+// inline, with NO second modal (stacked page-level modals don't interact here).
+// It only *stages* a choice: the caller 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.
+import type { TaskSearchResult, TaskSourceKind } from '~/types/domain'
+
+const props = defineProps<{
+  /** contextKeys already staged by the caller, so they're filtered out / not re-offered. */
+  chosenKeys?: string[]
+}>()
+const emit = defineEmits<{ pick: [item: PendingContext] }>()
+
+const tasks = useTasksStore()
+
+const chosen = computed(() => new Set(props.chosenKeys ?? []))
+
+// Source: default to the first offered tracker; a selector appears only when more
+// than one is offered (the common case is a single source).
+const source = ref<TaskSourceKind | undefined>(tasks.offeredSources[0]?.source)
+const sourceItems = computed(() =>
+  tasks.offeredSources.map((s) => ({ label: s.label, value: s.source })),
+)
+const descriptor = computed(() => (source.value ? tasks.descriptorFor(source.value) : undefined))
+const searchable = computed(() => descriptor.value?.searchable ?? false)
+
+const query = ref('')
+const results = ref<TaskSearchResult[]>([])
+const searching = ref(false)
+const searchError = ref<string | null>(null)
+
+// Debounced search: free text hits the tracker; a query that's clearly a URL/key
+// is left to the explicit "by reference" row below (search won't surface it).
+let timer: ReturnType<typeof setTimeout> | undefined
+watch([query, source], () => {
+  if (timer) clearTimeout(timer)
+  results.value = []
+  searchError.value = null
+  const q = query.value.trim()
+  if (!q || !searchable.value) return
+  timer = setTimeout(runSearch, 300)
+})
+
+async function runSearch() {
+  const q = query.value.trim()
+  if (!q || !source.value) return
+  searching.value = true
+  searchError.value = null
+  try {
+    results.value = await tasks.search(source.value, q)
+  } catch (e) {
+    results.value = []
+    searchError.value = e instanceof Error ? e.message : String(e)
+  } finally {
+    searching.value = false
+  }
+}
+
+const icon = computed(() => descriptor.value?.icon ?? 'i-lucide-square-check')
+
+function keyFor(externalId: string): string {
+  return source.value
+    ? contextKey({ kind: 'task', source: source.value, externalId })
+    : `task::${externalId}`
+}
+
+// Already-imported issues for this source, filtered by the query and never
+// re-offering one the caller already staged.
+const importedRows = computed(() => {
+  if (!source.value) return []
+  const q = query.value.trim().toLowerCase()
+  return tasks.tasks
+    .filter((t) => t.source === source.value)
+    .filter((t) => !chosen.value.has(keyFor(t.externalId)))
+    .filter(
+      (t) => !q || t.externalId.toLowerCase().includes(q) || t.title.toLowerCase().includes(q),
+    )
+})
+
+// Search hits not already imported (those show in importedRows) and not staged.
+const searchRows = computed(() => {
+  if (!source.value) return []
+  const importedIds = new Set(
+    tasks.tasks.filter((t) => t.source === source.value).map((t) => t.externalId),
+  )
+  return results.value
+    .filter((r) => !importedIds.has(r.externalId))
+    .filter((r) => !chosen.value.has(keyFor(r.externalId)))
+})
+
+// A pasted URL / key the search won't match: offer it as an explicit reference.
+const refRow = computed(() => {
+  const q = query.value.trim()
+  if (!q || !source.value) return null
+  const known =
+    importedRows.value.some((t) => t.externalId === q) ||
+    searchRows.value.some((r) => r.externalId === q) ||
+    chosen.value.has(keyFor(q))
+  if (known) return null
+  // 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 empty = computed(
+  () =>
+    !searching.value &&
+    !searchError.value &&
+    importedRows.value.length === 0 &&
+    searchRows.value.length === 0 &&
+    refRow.value === null,
+)
+
+function pickImported(externalId: string, title: string, status: string) {
+  if (!source.value) return
+  emit('pick', {
+    kind: 'task',
+    source: source.value,
+    externalId,
+    title: `${externalId} · ${title}`,
+    subtitle: status || undefined,
+    icon: icon.value,
+    needsImport: false,
+  })
+}
+
+function pickSearch(r: TaskSearchResult) {
+  emit('pick', {
+    kind: 'task',
+    source: r.source,
+    externalId: r.externalId,
+    title: `${r.externalId} · ${r.title}`,
+    subtitle: r.status || undefined,
+    icon: icon.value,
+    needsImport: true,
+  })
+}
+
+function pickRef(q: string) {
+  if (!source.value) return
+  emit('pick', {
+    kind: 'task',
+    source: source.value,
+    externalId: q,
+    title: q,
+    subtitle: descriptor.value?.label,
+    icon: icon.value,
+    needsImport: true,
+  })
+  query.value = ''
+}
+
+onMounted(() => {
+  // Keep the quick-pick list current (cheap; the store dedupes).
+  tasks.loadTasks().catch(() => {})
+})
+</script>
+
+<template>
+  <div class="space-y-2 rounded-lg border border-slate-800 bg-slate-900/40 p-2">
+    <USelect
+      v-if="sourceItems.length > 1"
+      v-model="source"
+      :items="sourceItems"
+      size="xs"
+      class="w-full"
+    />
+
+    <UInput
+      v-model="query"
+      :icon="searching ? 'i-lucide-loader-circle' : 'i-lucide-search'"
+      :ui="{ leadingIcon: searching ? 'animate-spin' : '' }"
+      size="sm"
+      class="w-full"
+      :placeholder="
+        searchable
+          ? 'Search issues or paste a URL/key…'
+          : (descriptor?.refPlaceholder ?? 'Paste an issue URL or key…')
+      "
+      @keydown.enter="refRow && pickRef(refRow)"
+    />
+
+    <p v-if="searchError" class="px-1 text-[11px] text-amber-400">
+      Search failed: {{ searchError }}
+    </p>
+
+    <div class="max-h-56 space-y-0.5 overflow-y-auto">
+      <!-- Already-imported issues (linked directly, no re-fetch). -->
+      <button
+        v-for="t in importedRows"
+        :key="`imp:${t.externalId}`"
+        type="button"
+        class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
+        @click="pickImported(t.externalId, t.title, t.status)"
+      >
+        <UIcon :name="icon" class="h-3.5 w-3.5 shrink-0 text-indigo-400" />
+        <span class="truncate">{{ t.externalId }} · {{ t.title }}</span>
+        <UBadge color="neutral" variant="soft" size="xs" class="ml-auto shrink-0">imported</UBadge>
+      </button>
+
+      <!-- Tracker search hits (imported on add). -->
+      <button
+        v-for="r in searchRows"
+        :key="`hit:${r.externalId}`"
+        type="button"
+        class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
+        @click="pickSearch(r)"
+      >
+        <UIcon :name="icon" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
+        <span class="truncate">{{ r.externalId }} · {{ r.title }}</span>
+        <UBadge v-if="r.status" color="neutral" variant="soft" size="xs" class="ml-auto shrink-0">
+          {{ r.status }}
+        </UBadge>
+      </button>
+
+      <!-- Explicit URL/key reference (imported on add). -->
+      <button
+        v-if="refRow"
+        type="button"
+        class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
+        @click="pickRef(refRow)"
+      >
+        <UIcon name="i-lucide-link" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
+        <span class="truncate"
+          >Attach <span class="text-slate-200">{{ refRow }}</span> by reference</span
+        >
+      </button>
+
+      <p v-if="empty" class="px-2 py-1.5 text-[11px] text-slate-500">
+        {{
+          query.trim()
+            ? 'No matching issues.'
+            : searchable
+              ? 'Search by title, or pick an imported issue.'
+              : 'Paste an issue URL or key to attach it.'
+        }}
+      </p>
+    </div>
+  </div>
+</template>

package/app/components/tasks/TaskImportModal.vue

@@ -5,7 +5,7 @@
 // or turned directly into a new board task here — pick a container (service frame
 // or module) and "Create task", which seeds a leaf block from the issue and links
 // the issue to it for context.
-import type { Block, TaskSourceKind } from '~/types/domain'
+import type { Block, TaskSearchResult, TaskSourceKind } from '~/types/domain'
 
 const ui = useUiStore()
 const tasks = useTasksStore()
@@ -27,6 +27,47 @@ const sourceItems = computed(() =>
   tasks.offeredSources.map((s) => ({ label: s.label, value: s.source })),
 )
 const descriptor = computed(() => (source.value ? tasks.descriptorFor(source.value) : undefined))
+const searchable = computed(() => descriptor.value?.searchable ?? false)
+
+// Browse the tracker by free text so an issue can be turned into a task without
+// knowing its key. Debounced; a created/imported hit also lands in the list below.
+const searchQuery = ref('')
+const searchResults = ref<TaskSearchResult[]>([])
+const searching = ref(false)
+const searchError = ref<string | null>(null)
+
+let searchTimer: ReturnType<typeof setTimeout> | undefined
+watch([searchQuery, source], () => {
+  if (searchTimer) clearTimeout(searchTimer)
+  searchResults.value = []
+  searchError.value = null
+  const q = searchQuery.value.trim()
+  if (!q || !searchable.value) return
+  searchTimer = setTimeout(runSearch, 300)
+})
+
+async function runSearch() {
+  const q = searchQuery.value.trim()
+  if (!q || !source.value) return
+  searching.value = true
+  searchError.value = null
+  try {
+    searchResults.value = await tasks.search(source.value, q)
+  } catch (e) {
+    searchResults.value = []
+    searchError.value = e instanceof Error ? e.message : String(e)
+  } finally {
+    searching.value = false
+  }
+}
+
+// Search hits not yet imported (imported ones already render in the list below).
+const importedIds = computed(
+  () => new Set(tasks.tasks.filter((t) => t.source === source.value).map((t) => t.externalId)),
+)
+const freshHits = computed(() =>
+  searchResults.value.filter((r) => !importedIds.value.has(r.externalId)),
+)
 
 const sourceTasks = computed(() =>
   source.value ? tasks.tasks.filter((t) => t.source === source.value) : [],
@@ -52,6 +93,9 @@ const creatingId = ref<string | null>(null)
 watch(open, (isOpen) => {
   if (isOpen) {
     ref_.value = ''
+    searchQuery.value = ''
+    searchResults.value = []
+    searchError.value = null
     source.value = ui.taskImport?.source ?? tasks.offeredSources[0]?.source ?? undefined
     containerId.value = containerItems.value[0]?.value
     creatingId.value = null
@@ -59,10 +103,14 @@ watch(open, (isOpen) => {
   }
 })
 
-async function createTask(externalId: string) {
+// Create a board task from an issue, seeding its title/description from the issue
+// and linking it back for writeback. A search hit isn't projected locally yet, so
+// `needsImport` fetches + persists it first (create-block requires it imported).
+async function createTask(externalId: string, needsImport = false) {
   if (!source.value || !containerId.value) return
   creatingId.value = externalId
   try {
+    if (needsImport) await tasks.importTask(source.value, externalId)
     const { block } = await tasks.createTaskFromIssue(source.value, externalId, containerId.value)
     board.upsert(block as Block)
     toast.add({ title: `Created task "${block.title}"`, icon: 'i-lucide-square-check' })
@@ -100,7 +148,7 @@ async function doImport() {
 </script>
 
 <template>
-  <UModal v-model:open="open" title="Import from a task source">
+  <UModal v-model:open="open" title="Tracker issues">
     <template #body>
       <!-- Empty state: no source offered (none connected/installed, or all disabled) -->
       <div v-if="!tasks.anyOffered" class="space-y-3 text-center">
@@ -146,21 +194,90 @@ async function doImport() {
           </UButton>
         </div>
 
+        <!-- Browse: search the tracker by title so an issue can be turned into a
+             task without knowing its key. -->
+        <UFormField v-if="searchable" label="Search issues">
+          <UInput
+            v-model="searchQuery"
+            :icon="searching ? 'i-lucide-loader-circle' : 'i-lucide-search'"
+            :ui="{ leadingIcon: searching ? 'animate-spin' : '' }"
+            placeholder="Search by title…"
+            class="w-full"
+          />
+        </UFormField>
+
+        <!-- Shared target container for every "Create task" action below. -->
+        <UFormField
+          v-if="containerItems.length && (freshHits.length || sourceTasks.length)"
+          label="Create tasks in"
+          class="w-72"
+        >
+          <USelect
+            v-model="containerId"
+            :items="containerItems"
+            placeholder="Pick a frame or module"
+            class="w-full"
+          />
+        </UFormField>
+        <p
+          v-else-if="!containerItems.length && (freshHits.length || sourceTasks.length)"
+          class="text-[11px] text-slate-500"
+        >
+          Add a service frame to the board first to create tasks from issues.
+        </p>
+
+        <!-- Search results (not yet imported): create a task directly from a hit. -->
+        <div v-if="searchError" class="text-[11px] text-amber-400">
+          Search failed: {{ searchError }}
+        </div>
+        <div v-if="freshHits.length" class="space-y-2">
+          <h3 class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            Search results
+          </h3>
+          <div
+            v-for="hit in freshHits"
+            :key="`hit:${hit.source}:${hit.externalId}`"
+            class="rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+          >
+            <div class="flex items-start justify-between gap-2">
+              <div class="min-w-0">
+                <a
+                  :href="hit.url"
+                  target="_blank"
+                  rel="noopener"
+                  class="truncate text-sm font-medium text-white hover:underline"
+                >
+                  {{ hit.externalId }} · {{ hit.title }}
+                </a>
+                <p v-if="hit.excerpt" class="mt-0.5 line-clamp-2 text-xs text-slate-500">
+                  {{ hit.excerpt }}
+                </p>
+              </div>
+              <div class="flex shrink-0 items-center gap-2">
+                <UBadge v-if="hit.status" color="neutral" variant="soft" size="xs">
+                  {{ hit.status }}
+                </UBadge>
+                <UButton
+                  color="primary"
+                  variant="soft"
+                  size="xs"
+                  icon="i-lucide-square-check"
+                  :loading="creatingId === hit.externalId"
+                  :disabled="!containerId || creatingId !== null"
+                  @click="createTask(hit.externalId, true)"
+                >
+                  Create task
+                </UButton>
+              </div>
+            </div>
+          </div>
+        </div>
+
         <!-- List of already-imported issues -->
         <div v-if="sourceTasks.length" class="space-y-2">
-          <div class="flex items-end justify-between gap-3">
-            <h3 class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
-              Imported issues
-            </h3>
-            <UFormField v-if="containerItems.length" label="Create tasks in" size="xs" class="w-56">
-              <USelect
-                v-model="containerId"
-                :items="containerItems"
-                placeholder="Pick a frame or module"
-                class="w-full"
-              />
-            </UFormField>
-          </div>
+          <h3 class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            Imported issues
+          </h3>
           <div
             v-for="task in sourceTasks"
             :key="`${task.source}:${task.externalId}`"
@@ -196,11 +313,13 @@ async function doImport() {
               </div>
             </div>
           </div>
-          <p v-if="!containerItems.length" class="text-[11px] text-slate-500">
-            Add a service frame to the board first to create tasks from issues.
-          </p>
         </div>
-        <p v-else class="text-center text-xs text-slate-500">No issues imported yet.</p>
+        <p
+          v-else-if="!freshHits.length && !searchQuery.trim()"
+          class="text-center text-xs text-slate-500"
+        >
+          No issues imported yet. Search above, or paste an issue URL/key to import one.
+        </p>
       </div>
     </template>
   </UModal>

package/app/composables/api/tasks.ts

@@ -3,6 +3,7 @@ import type {
   SourceTask,
   TaskConnection,
   TaskSearchResult,
+  TaskSourceDiagnostic,
   TaskSourceKind,
   TaskSourceState,
 } from '~/types/domain'
@@ -41,6 +42,13 @@ export function tasksApi({ http, ws }: ApiContext) {
     disconnectTaskSource: (workspaceId: string, source: TaskSourceKind) =>
       http(`${ws(workspaceId)}/task-sources/${source}/connection`, { method: 'DELETE' }),
 
+    // Live "check setup" probe: authenticates against the source and reads a slice
+    // of its issues API, returning a classified verdict the panel renders verbatim.
+    checkTaskSource: (workspaceId: string, source: TaskSourceKind) =>
+      http<TaskSourceDiagnostic>(`${ws(workspaceId)}/task-sources/${source}/diagnostics`, {
+        method: 'POST',
+      }),
+
     listTasks: (workspaceId: string) => http<SourceTask[]>(`${ws(workspaceId)}/tasks`),
 
     importTask: (workspaceId: string, source: TaskSourceKind, body: { ref: string }) =>

package/app/stores/tasks.ts

@@ -4,6 +4,7 @@ import type {
   SourceTask,
   TaskConnection,
   TaskSearchResult,
+  TaskSourceDiagnostic,
   TaskSourceKind,
   TaskSourceState,
 } from '~/types/domain'
@@ -27,11 +28,21 @@ export const useTasksStore = defineStore('tasks', () => {
 
   /** null = unknown (not probed yet), true/false = integration on/off. */
   const available = ref<boolean | null>(null)
+  /**
+   * Why the last probe failed, when it did — captured (rather than swallowed) so
+   * the settings panel can explain *why* nothing is surfaced (integration disabled
+   * vs a server/backend error) instead of a blanket "install integration first".
+   */
+  const probeError = ref<{ status: number | null; message: string } | null>(null)
   /** The configured sources, each with its descriptor + per-workspace state (available + enabled). */
   const sources = ref<TaskSourceState[]>([])
   /** Live connections, one per connected (credentialed) source. */
   const connections = ref<TaskConnection[]>([])
   const tasks = ref<SourceTask[]>([])
+  /** The last live setup-check verdict per source (from `checkSetup`). */
+  const diagnostics = ref<Partial<Record<TaskSourceKind, TaskSourceDiagnostic>>>({})
+  /** The source currently running a setup check, if any. */
+  const checking = ref<TaskSourceKind | null>(null)
   const loading = ref(false)
 
   /** Sources the workspace currently has a live connection to. */
@@ -85,16 +96,43 @@ export const useTasksStore = defineStore('tasks', () => {
         api.listTaskConnections(workspace.requireId()),
       ])
       available.value = true
+      probeError.value = null
       sources.value = srcs
       connections.value = conns
-    } catch {
-      // 503 (integration disabled) or any error → hide the UI entry points.
+    } catch (e) {
+      // 503 (integration disabled) or any error → hide the UI entry points, but keep
+      // the reason so the settings panel can explain it (a 503 is "turned off on this
+      // deployment"; a 500 is "the backend errored — e.g. a migration isn't applied").
       available.value = false
+      const err = e as { statusCode?: number; data?: { error?: { message?: string } } }
+      const serverMessage = err?.data?.error?.message
+      probeError.value = {
+        status: err?.statusCode ?? null,
+        message: serverMessage || (e instanceof Error ? e.message : String(e)),
+      }
       sources.value = []
       connections.value = []
     }
   }
 
+  /**
+   * Run a live setup check for a source (authenticate + read), caching the verdict
+   * so the panel can show exactly what's wrong (missing App / wrong token / lacking
+   * the Issues permission) and how to fix it. Re-probes on success so a
+   * just-fixed source flips `available`/`enabled` without a manual reload.
+   */
+  async function checkSetup(source: TaskSourceKind): Promise<TaskSourceDiagnostic> {
+    checking.value = source
+    try {
+      const result = await api.checkTaskSource(workspace.requireId(), source)
+      diagnostics.value = { ...diagnostics.value, [source]: result }
+      if (result.ok) await probe()
+      return result
+    } finally {
+      checking.value = null
+    }
+  }
+
   /** Connect the workspace to a source with its credential bag. */
   async function connect(source: TaskSourceKind, credentials: Record<string, string>) {
     const conn = await api.connectTaskSource(workspace.requireId(), source, credentials)
@@ -165,9 +203,12 @@ export const useTasksStore = defineStore('tasks', () => {
 
   return {
     available,
+    probeError,
     sources,
     connections,
     tasks,
+    diagnostics,
+    checking,
     loading,
     connectedSources,
     anyConnected,
@@ -178,6 +219,7 @@ export const useTasksStore = defineStore('tasks', () => {
     isConnected,
     tasksForBlock,
     probe,
+    checkSetup,
     connect,
     disconnect,
     setEnabled,

package/app/types/tasks.ts

@@ -37,6 +37,31 @@ export interface TaskSourceState extends TaskSourceDescriptor {
   enabled: boolean
 }
 
+/**
+ * The verdict of a live "check setup" probe against a source (mirrors
+ * `@cat-factory/contracts`). Unlike `available` (a passive row-exists flag) this
+ * is the result of actually authenticating + reading, so it distinguishes a
+ * configured-but-broken source from a working one.
+ */
+export type TaskSourceDiagnosticStatus =
+  | 'ready'
+  | 'not_installed'
+  | 'not_connected'
+  | 'auth_failed'
+  | 'forbidden'
+  | 'unreachable'
+  | 'error'
+
+export interface TaskSourceDiagnostic {
+  source: TaskSourceKind
+  ok: boolean
+  status: TaskSourceDiagnosticStatus
+  /** A one-line, actionable explanation shown verbatim in the panel. */
+  message: string
+  /** Optional extra context (account login, repo count, signed-in user). */
+  detail?: string | null
+}
+
 /** A workspace's connection to a task source (never carries credentials). */
 export interface TaskConnection {
   source: TaskSourceKind

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",

package/app/components/settings/IssueTrackerWritebackPanel.vue

@@ -1,91 +0,0 @@
-<script setup lang="ts">
-// Workspace settings: issue-tracker writeback. Two independent toggles that govern
-// whether the engine writes back to a task's linked tracker issue(s) as its PR
-// progresses — comment when the PR opens, and comment + close as resolved when it
-// merges. Each is overridable per task in the inspector. Persisted on the workspace
-// tracker settings (the selection + Jira project key are preserved on save).
-import { onMounted, ref, watch } from 'vue'
-
-const tracker = useTrackerStore()
-const toast = useToast()
-
-const commentOnPrOpen = ref(false)
-const resolveOnMerge = ref(false)
-const saving = ref(false)
-
-// Sync the local toggles from the store on mount (the tab renders when Workspace
-// settings opens) and whenever the stored settings change underneath.
-function hydrate() {
-  commentOnPrOpen.value = tracker.settings.writebackCommentOnPrOpen
-  resolveOnMerge.value = tracker.settings.writebackResolveOnMerge
-}
-onMounted(hydrate)
-watch(() => tracker.settings, hydrate, { deep: true })
-
-async function save() {
-  saving.value = true
-  try {
-    // Preserve the tracker selection + Jira project key; only the writeback flags change.
-    await tracker.save({
-      tracker: tracker.settings.tracker,
-      jiraProjectKey: tracker.settings.jiraProjectKey,
-      writebackCommentOnPrOpen: commentOnPrOpen.value,
-      writebackResolveOnMerge: resolveOnMerge.value,
-    })
-    toast.add({ title: 'Writeback settings saved', icon: 'i-lucide-check', color: 'success' })
-  } catch (e) {
-    toast.add({
-      title: 'Could not save settings',
-      description: e instanceof Error ? e.message : String(e),
-      icon: 'i-lucide-triangle-alert',
-      color: 'error',
-    })
-  } finally {
-    saving.value = false
-  }
-}
-</script>
-
-<template>
-  <div class="space-y-4">
-    <p class="text-xs text-slate-400">
-      When a task is linked to a tracker issue (GitHub Issues or Jira), write back to it as the
-      task's pull request progresses. Each toggle is the workspace default and can be overridden per
-      task in the inspector. GitHub issues close natively; Jira issues transition to the first
-      status in their <span class="text-slate-300">Done</span> category.
-    </p>
-
-    <label class="flex items-start gap-3 rounded-lg border border-slate-700 bg-slate-800/40 p-3">
-      <USwitch v-model="commentOnPrOpen" />
-      <span class="text-sm">
-        <span class="block text-slate-200">Comment when a PR opens</span>
-        <span class="block text-xs text-slate-500">
-          Post a comment on the linked issue with the new pull request's link.
-        </span>
-      </span>
-    </label>
-
-    <label class="flex items-start gap-3 rounded-lg border border-slate-700 bg-slate-800/40 p-3">
-      <USwitch v-model="resolveOnMerge" />
-      <span class="text-sm">
-        <span class="block text-slate-200">Close as resolved when a PR merges</span>
-        <span class="block text-xs text-slate-500">
-          Comment that the PR merged, then close / resolve the linked issue.
-        </span>
-      </span>
-    </label>
-
-    <div class="flex justify-end">
-      <UButton
-        color="primary"
-        variant="soft"
-        size="sm"
-        icon="i-lucide-save"
-        :loading="saving"
-        @click="save"
-      >
-        Save
-      </UButton>
-    </div>
-  </div>
-</template>